claunia/flac
1
0
Fork 0
mirror of https://github.com/claunia/flac.git synced 2025-12-16 18:54:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

merge down from merged-API-layer branch: cvs -q up -dP -j API_LAYER_MERGING_BASELINE -j API_LAYER_MERGING_BRANCH

Browse Source
This commit is contained in:
Josh Coalson
2006-09-13 01:42:27 +00:00
parent 461f3eb260
commit 6b21f66784
156 changed files with 8320 additions and 31342 deletions
Download Patch File Download Diff File Expand all files Collapse all files

328
include/FLAC++/decoder.h
View File

@@ -34,8 +34,7 @@
#include "export.h"
#include "FLAC/file_decoder.h"
#include "FLAC/seekable_stream_decoder.h"
#include <string>
#include "FLAC/stream_decoder.h"
@@ -53,40 +52,57 @@
* \ingroup flacpp
*
* \brief
* This module describes the three decoder layers provided by libFLAC++.
* This module describes the decoder layers provided by libFLAC++.
*
* The libFLAC++ decoder classes are object wrappers around their
* counterparts in libFLAC. All three decoding layers available in
* counterparts in libFLAC. All decoding layers available in
* libFLAC are also provided here. The interface is very similar;
* make sure to read the \link flac_decoder libFLAC decoder module \endlink.
*
* The only real difference here is that instead of passing in C function
* pointers for callbacks, you inherit from the decoder class and provide
* implementations for the callbacks in the derived class; because of this
* there is no need for a 'client_data' property.
* There are only two significant differences here. First, instead of
* passing in C function pointers for callbacks, you inherit from the
* decoder class and provide implementations for the callbacks in your
* derived class; because of this there is no need for a 'client_data'
* property.
*
* Second, there are two stream decoder classes. FLAC::Decoder::Stream
* is used for the same cases that FLAC__stream_decoder_init_stream() is
* used, and FLAC::Decoder::File is used for the same cases that
* FLAC__stream_decoder_init_FILE() and FLAC__stream_decoder_init_file()
* are used.
*/
namespace FLAC {
namespace Decoder {
// ============================================================
//
// Equivalent: FLAC__StreamDecoder
//
// ============================================================
/** \defgroup flacpp_stream_decoder FLAC++/decoder.h: stream decoder class
* \ingroup flacpp_decoder
*
* \brief
* This class wraps the ::FLAC__StreamDecoder.
*
* See the \link flac_stream_decoder libFLAC stream decoder module \endlink.
* See the \link flac_stream_decoder libFLAC stream decoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::FLAC__StreamDecoder.
/** This class wraps the ::FLAC__StreamDecoder. If you are
* decoding from a file, FLAC::Decoder::File may be more
* convenient.
*
* The usage of this class is similar to FLAC__StreamDecoder,
* except instead of providing callbacks to
* FLAC__stream_decoder_init_stream(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call Stream::init(). The rest of
* the calls work the same as in the C layer.
*
* Only the read, write, and error callbacks are mandatory. The
* others are optional; this class provides default
* implementations that do nothing. In order for seeking to work
* you must overide seek_callback(), tell_callback(),
* length_callback(), and eof_callback().
*/
class FLACPP_API Stream {
public:
@@ -103,42 +119,74 @@ namespace FLAC {
Stream();
virtual ~Stream();
/** Call after construction to check the that the object was created
* successfully. If not, use get_state() to find out why not.
*
* \{
*/
bool is_valid() const;
inline operator bool() const { return is_valid(); }
/* \} */
bool set_metadata_respond(::FLAC__MetadataType type);
bool set_metadata_respond_application(const FLAC__byte id[4]);
bool set_metadata_respond_all();
bool set_metadata_ignore(::FLAC__MetadataType type);
bool set_metadata_ignore_application(const FLAC__byte id[4]);
bool set_metadata_ignore_all();
bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking()
bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond()
bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
bool set_metadata_respond_all(); ///< See FLAC__stream_decoder_set_metadata_respond_all()
bool set_metadata_ignore(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_ignore()
bool set_metadata_ignore_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_ignore_application()
bool set_metadata_ignore_all(); ///< See FLAC__stream_decoder_set_metadata_ignore_all()
State get_state() const;
unsigned get_channels() const;
::FLAC__ChannelAssignment get_channel_assignment() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
State get_state() const; ///< See FLAC__stream_decoder_get_state()
bool get_md5_checking() const; ///< See FLAC__stream_decoder_get_md5_checking()
FLAC__uint64 get_total_samples() const; ///< See FLAC__stream_decoder_get_total_samples()
unsigned get_channels() const; ///< See FLAC__stream_decoder_get_channels()
::FLAC__ChannelAssignment get_channel_assignment() const; ///< See FLAC__stream_decoder_get_channel_assignment()
unsigned get_bits_per_sample() const; ///< See FLAC__stream_decoder_get_bits_per_sample()
unsigned get_sample_rate() const; ///< See FLAC__stream_decoder_get_sample_rate()
unsigned get_blocksize() const; ///< See FLAC__stream_decoder_get_blocksize()
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_decoder_init_stream().
*/
State init();
::FLAC__StreamDecoderInitStatus init();
void finish();
void finish(); ///< See FLAC__stream_decoder_finish()
bool flush();
bool reset();
bool flush(); ///< See FLAC__stream_decoder_flush()
bool reset(); ///< See FLAC__stream_decoder_reset()
bool process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_stream();
bool skip_single_frame();
bool process_single(); ///< See FLAC__stream_decoder_process_single()
bool process_until_end_of_metadata(); ///< See FLAC__stream_decoder_process_until_end_of_metadata()
bool process_until_end_of_stream(); ///< See FLAC__stream_decoder_process_until_end_of_stream()
bool skip_single_frame(); ///< See FLAC__stream_decoder_skip_single_frame()
bool seek_absolute(FLAC__uint64 sample); ///< See FLAC__stream_decoder_seek_absolute()
protected:
/// see FLAC__StreamDecoderReadCallback
virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
/// see FLAC__StreamDecoderSeekCallback
virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
/// see FLAC__StreamDecoderTellCallback
virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
/// see FLAC__StreamDecoderLengthCallback
virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
/// see FLAC__StreamDecoderEofCallback
virtual bool eof_callback();
/// see FLAC__StreamDecoderWriteCallback
virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
/// see FLAC__StreamDecoderMetadataCallback
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
/// see FLAC__StreamDecoderErrorCallback
virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
@@ -146,12 +194,16 @@ namespace FLAC {
friend State;
#endif
::FLAC__StreamDecoder *decoder_;
private:
static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
private:
// Private and undefined so you can't use them:
Stream(const Stream &);
void operator=(const Stream &);
@@ -159,186 +211,56 @@ namespace FLAC {
/* \} */
// ============================================================
//
// Equivalent: FLAC__SeekableStreamDecoder
//
// ============================================================
/** \defgroup flacpp_seekable_stream_decoder FLAC++/decoder.h: seekable stream decoder class
* \ingroup flacpp_decoder
*
* \brief
* This class wraps the ::FLAC__SeekableStreamDecoder.
*
* See the \link flac_seekable_stream_decoder libFLAC seekable stream decoder module \endlink.
*
* \{
*/
/** This class wraps the ::FLAC__SeekableStreamDecoder.
*/
class FLACPP_API SeekableStream {
public:
class FLACPP_API State {
public:
inline State(::FLAC__SeekableStreamDecoderState state): state_(state) { }
inline operator ::FLAC__SeekableStreamDecoderState() const { return state_; }
inline const char *as_cstring() const { return ::FLAC__SeekableStreamDecoderStateString[state_]; }
inline const char *resolved_as_cstring(const SeekableStream &decoder) const { return ::FLAC__seekable_stream_decoder_get_resolved_state_string(decoder.decoder_); }
protected:
::FLAC__SeekableStreamDecoderState state_;
};
SeekableStream();
virtual ~SeekableStream();
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_md5_checking(bool value);
bool set_metadata_respond(::FLAC__MetadataType type);
bool set_metadata_respond_application(const FLAC__byte id[4]);
bool set_metadata_respond_all();
bool set_metadata_ignore(::FLAC__MetadataType type);
bool set_metadata_ignore_application(const FLAC__byte id[4]);
bool set_metadata_ignore_all();
State get_state() const;
Stream::State get_stream_decoder_state() const;
bool get_md5_checking() const;
unsigned get_channels() const;
::FLAC__ChannelAssignment get_channel_assignment() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
State init();
bool finish();
bool flush();
bool reset();
bool process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_stream();
bool skip_single_frame();
bool seek_absolute(FLAC__uint64 sample);
protected:
virtual ::FLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
virtual ::FLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
virtual ::FLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
virtual ::FLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
virtual bool eof_callback() = 0;
virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::FLAC__SeekableStreamDecoder *decoder_;
private:
static ::FLAC__SeekableStreamDecoderReadStatus read_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static ::FLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
static FLAC__bool eof_callback_(const ::FLAC__SeekableStreamDecoder *decoder, void *client_data);
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::FLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::FLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
// Private and undefined so you can't use them:
SeekableStream(const SeekableStream &);
void operator=(const SeekableStream &);
};
/* \} */
// ============================================================
//
// Equivalent: FLAC__FileDecoder
//
// ============================================================
/** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
* \ingroup flacpp_decoder
*
* \brief
* This class wraps the ::FLAC__FileDecoder.
* This class wraps the ::FLAC__StreamDecoder.
*
* See the \link flac_file_decoder libFLAC file decoder module \endlink.
* See the \link flac_stream_decoder libFLAC stream decoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::FLAC__FileDecoder.
/** This class wraps the ::FLAC__StreamDecoder. If you are
* not decoding from a file, you may need to use
* FLAC::Decoder::Stream.
*
* The usage of this class is similar to FLAC__StreamDecoder,
* except instead of providing callbacks to
* FLAC__stream_decoder_init_FILE() or
* FLAC__stream_decoder_init_file(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call File::init(). The rest of
* the calls work the same as in the C layer.
*
* Only the write, and error callbacks from FLAC::Decoder::Stream
* are mandatory. The others are optional; this class provides
* full working implementations for all other callbacks and
* supports seeking.
*/
class FLACPP_API File {
class FLACPP_API File: public Stream {
public:
class FLACPP_API State {
public:
inline State(::FLAC__FileDecoderState state): state_(state) { }
inline operator ::FLAC__FileDecoderState() const { return state_; }
inline const char *as_cstring() const { return ::FLAC__FileDecoderStateString[state_]; }
inline const char *resolved_as_cstring(const File &decoder) const { return ::FLAC__file_decoder_get_resolved_state_string(decoder.decoder_); }
protected:
::FLAC__FileDecoderState state_;
};
File();
virtual ~File();
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_md5_checking(bool value);
bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin
bool set_metadata_respond(::FLAC__MetadataType type);
bool set_metadata_respond_application(const FLAC__byte id[4]);
bool set_metadata_respond_all();
bool set_metadata_ignore(::FLAC__MetadataType type);
bool set_metadata_ignore_application(const FLAC__byte id[4]);
bool set_metadata_ignore_all();
State get_state() const;
SeekableStream::State get_seekable_stream_decoder_state() const;
Stream::State get_stream_decoder_state() const;
bool get_md5_checking() const;
unsigned get_channels() const;
::FLAC__ChannelAssignment get_channel_assignment() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
State init();
bool finish();
bool process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_file();
bool skip_single_frame();
bool seek_absolute(FLAC__uint64 sample);
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_decoder_init_FILE() and
* FLAC__stream_decoder_init_file().
* \{
*/
::FLAC__StreamDecoderInitStatus init(FILE *file);
::FLAC__StreamDecoderInitStatus init(const char *filename);
::FLAC__StreamDecoderInitStatus init(const std::string &filename);
/* \} */
protected:
virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::FLAC__FileDecoder *decoder_;
// this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
private:
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::FLAC__FileDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::FLAC__FileDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
// Private and undefined so you can't use them:
File(const File &);
void operator=(const File &);

380
include/FLAC++/encoder.h
View File

@@ -34,8 +34,6 @@
#include "export.h"
#include "FLAC/file_encoder.h"
#include "FLAC/seekable_stream_encoder.h"
#include "FLAC/stream_encoder.h"
#include "decoder.h"
#include "metadata.h"
@@ -55,40 +53,58 @@
* \ingroup flacpp
*
* \brief
* This module describes the three encoder layers provided by libFLAC++.
* This module describes the encoder layers provided by libFLAC++.
*
* The libFLAC++ encoder classes are object wrappers around their
* counterparts in libFLAC. All three encoding layers available in
* counterparts in libFLAC. All decoding layers available in
* libFLAC are also provided here. The interface is very similar;
* make sure to read the \link flac_encoder libFLAC encoder module \endlink.
*
* The only real difference here is that instead of passing in C function
* pointers for callbacks, you inherit from the encoder class and provide
* implementations for the callbacks in the derived class; because of this
* there is no need for a 'client_data' property.
* There are only two significant differences here. First, instead of
* passing in C function pointers for callbacks, you inherit from the
* encoder class and provide implementations for the callbacks in your
* derived class; because of this there is no need for a 'client_data'
* property.
*
* Second, there are two stream encoder classes. FLAC::Encoder::Stream
* is used for the same cases that FLAC__stream_encoder_init_stream() is
* used, and FLAC::Encoder::File is used for the same cases that
* FLAC__stream_encoder_init_FILE() and FLAC__stream_encoder_init_file()
* are used.
*/
namespace FLAC {
namespace Encoder {
// ============================================================
//
// Equivalent: FLAC__StreamEncoder
//
// ============================================================
/** \defgroup flacpp_stream_encoder FLAC++/encoder.h: stream encoder class
* \ingroup flacpp_encoder
*
* \brief
* This class wraps the ::FLAC__StreamEncoder.
*
* See the \link flac_stream_encoder libFLAC stream encoder module \endlink.
* See the \link flac_stream_encoder libFLAC stream encoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::FLAC__StreamEncoder.
/** This class wraps the ::FLAC__StreamEncoder. If you are
* encoding to a file, FLAC::Encoder::File may be more
* convenient.
*
* The usage of this class is similar to FLAC__StreamEncoder,
* except instead of providing callbacks to
* FLAC__stream_encoder_init_stream(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call Stream::init(). The rest of
* the calls work the same as in the C layer.
*
* Only the write callback is mandatory. The others are
* optional; this class provides default implementations that do
* nothing. In order for some STREAMINFO and SEEKTABLE data to
* be written properly, you must overide seek_callback() and
* tell_callback(); see FLAC__stream_encoder_init_stream() as to
* why.
*/
class FLACPP_API Stream {
public:
@@ -105,70 +121,93 @@ namespace FLAC {
Stream();
virtual ~Stream();
/** Call after construction to check the that the object was created
* successfully. If not, use get_state() to find out why not.
*
* \{
*/
bool is_valid() const;
inline operator bool() const { return is_valid(); }
/* \} */
bool set_verify(bool value);
bool set_streamable_subset(bool value);
bool set_do_mid_side_stereo(bool value);
bool set_loose_mid_side_stereo(bool value);
bool set_channels(unsigned value);
bool set_bits_per_sample(unsigned value);
bool set_sample_rate(unsigned value);
bool set_blocksize(unsigned value);
bool set_apodization(const char *specification);
bool set_max_lpc_order(unsigned value);
bool set_qlp_coeff_precision(unsigned value);
bool set_do_qlp_coeff_prec_search(bool value);
bool set_do_escape_coding(bool value);
bool set_do_exhaustive_model_search(bool value);
bool set_min_residual_partition_order(unsigned value);
bool set_max_residual_partition_order(unsigned value);
bool set_rice_parameter_search_dist(unsigned value);
bool set_total_samples_estimate(FLAC__uint64 value);
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks);
bool set_verify(bool value); ///< See FLAC__stream_encoder_set_verify()
bool set_streamable_subset(bool value); ///< See FLAC__stream_encoder_set_streamable_subset()
bool set_do_mid_side_stereo(bool value); ///< See FLAC__stream_encoder_set_do_mid_side_stereo()
bool set_loose_mid_side_stereo(bool value); ///< See FLAC__stream_encoder_set_loose_mid_side_stereo()
bool set_channels(unsigned value); ///< See FLAC__stream_encoder_set_channels()
bool set_bits_per_sample(unsigned value); ///< See FLAC__stream_encoder_set_bits_per_sample()
bool set_sample_rate(unsigned value); ///< See FLAC__stream_encoder_set_sample_rate()
bool set_blocksize(unsigned value); ///< See FLAC__stream_encoder_set_blocksize()
bool set_apodization(const char *specification); ///< See FLAC__stream_encoder_set_apodization()
bool set_max_lpc_order(unsigned value); ///< See FLAC__stream_encoder_set_max_lpc_order()
bool set_qlp_coeff_precision(unsigned value); ///< See FLAC__stream_encoder_set_qlp_coeff_precision()
bool set_do_qlp_coeff_prec_search(bool value); ///< See FLAC__stream_encoder_set_do_qlp_coeff_prec_search()
bool set_do_escape_coding(bool value); ///< See FLAC__stream_encoder_set_do_escape_coding()
bool set_do_exhaustive_model_search(bool value); ///< See FLAC__stream_encoder_set_do_exhaustive_model_search()
bool set_min_residual_partition_order(unsigned value); ///< See FLAC__stream_encoder_set_min_residual_partition_order()
bool set_max_residual_partition_order(unsigned value); ///< See FLAC__stream_encoder_set_max_residual_partition_order()
bool set_rice_parameter_search_dist(unsigned value); ///< See FLAC__stream_encoder_set_rice_parameter_search_dist()
bool set_total_samples_estimate(FLAC__uint64 value); ///< See FLAC__stream_encoder_set_total_samples_estimate()
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks); ///< See FLAC__stream_encoder_set_metadata()
bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks); ///< See FLAC__stream_encoder_set_metadata()
State get_state() const;
Decoder::Stream::State get_verify_decoder_state() const;
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
bool get_verify() const;
bool get_streamable_subset() const;
bool get_do_mid_side_stereo() const;
bool get_loose_mid_side_stereo() const;
unsigned get_channels() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
unsigned get_max_lpc_order() const;
unsigned get_qlp_coeff_precision() const;
bool get_do_qlp_coeff_prec_search() const;
bool get_do_escape_coding() const;
bool get_do_exhaustive_model_search() const;
unsigned get_min_residual_partition_order() const;
unsigned get_max_residual_partition_order() const;
unsigned get_rice_parameter_search_dist() const;
FLAC__uint64 get_total_samples_estimate() const;
State get_state() const; ///< See FLAC__stream_encoder_get_state()
Decoder::Stream::State get_verify_decoder_state() const; ///< See FLAC__stream_encoder_get_verify_decoder_state()
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); ///< See FLAC__stream_encoder_get_verify_decoder_error_stats()
bool get_verify() const; ///< See FLAC__stream_encoder_get_verify()
bool get_streamable_subset() const; ///< See FLAC__stream_encoder_get_streamable_subset()
bool get_do_mid_side_stereo() const; ///< See FLAC__stream_encoder_get_do_mid_side_stereo()
bool get_loose_mid_side_stereo() const; ///< See FLAC__stream_encoder_get_loose_mid_side_stereo()
unsigned get_channels() const; ///< See FLAC__stream_encoder_get_channels()
unsigned get_bits_per_sample() const; ///< See FLAC__stream_encoder_get_bits_per_sample()
unsigned get_sample_rate() const; ///< See FLAC__stream_encoder_get_sample_rate()
unsigned get_blocksize() const; ///< See FLAC__stream_encoder_get_blocksize()
unsigned get_max_lpc_order() const; ///< See FLAC__stream_encoder_get_max_lpc_order()
unsigned get_qlp_coeff_precision() const; ///< See FLAC__stream_encoder_get_qlp_coeff_precision()
bool get_do_qlp_coeff_prec_search() const; ///< See FLAC__stream_encoder_get_do_qlp_coeff_prec_search()
bool get_do_escape_coding() const; ///< See FLAC__stream_encoder_get_do_escape_coding()
bool get_do_exhaustive_model_search() const; ///< See FLAC__stream_encoder_get_do_exhaustive_model_search()
unsigned get_min_residual_partition_order() const; ///< See FLAC__stream_encoder_get_min_residual_partition_order()
unsigned get_max_residual_partition_order() const; ///< See FLAC__stream_encoder_get_max_residual_partition_order()
unsigned get_rice_parameter_search_dist() const; ///< See FLAC__stream_encoder_get_rice_parameter_search_dist()
FLAC__uint64 get_total_samples_estimate() const; ///< See FLAC__stream_encoder_get_total_samples_estimate()
State init();
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_encoder_init_stream().
*/
::FLAC__StreamEncoderInitStatus init();
void finish();
void finish(); ///< See FLAC__stream_encoder_finish()
bool process(const FLAC__int32 * const buffer[], unsigned samples);
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
bool process(const FLAC__int32 * const buffer[], unsigned samples); ///< See FLAC__stream_encoder_process()
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples); ///< See FLAC__stream_encoder_process_interleaved()
protected:
/// See FLAC__StreamEncoderWriteCallback
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
/// See FLAC__StreamEncoderSeekCallback
virtual ::FLAC__StreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
/// See FLAC__StreamEncoderTellCallback
virtual ::FLAC__StreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
/// See FLAC__StreamEncoderTellCallback
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::FLAC__StreamEncoder *encoder_;
private:
static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
static void metadata_callback_(const ::FLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
static ::FLAC__StreamEncoderSeekStatus seek_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__StreamEncoderTellStatus tell_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static void metadata_callback_(const ::FLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
private:
// Private and undefined so you can't use them:
Stream(const Stream &);
void operator=(const Stream &);
@@ -176,200 +215,61 @@ namespace FLAC {
/* \} */
/** \defgroup flacpp_seekable_stream_encoder FLAC++/encoder.h: seekable stream encoder class
* \ingroup flacpp_encoder
*
* \brief
* This class wraps the ::FLAC__SeekableStreamEncoder.
*
* See the \link flac_seekable_stream_encoder libFLAC seekable stream encoder module \endlink.
*
* \{
*/
/** This class wraps the ::FLAC__SeekableStreamEncoder.
*/
class FLACPP_API SeekableStream {
public:
class FLACPP_API State {
public:
inline State(::FLAC__SeekableStreamEncoderState state): state_(state) { }
inline operator ::FLAC__SeekableStreamEncoderState() const { return state_; }
inline const char *as_cstring() const { return ::FLAC__SeekableStreamEncoderStateString[state_]; }
inline const char *resolved_as_cstring(const SeekableStream &encoder) const { return ::FLAC__seekable_stream_encoder_get_resolved_state_string(encoder.encoder_); }
protected:
::FLAC__SeekableStreamEncoderState state_;
};
SeekableStream();
virtual ~SeekableStream();
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_verify(bool value);
bool set_streamable_subset(bool value);
bool set_do_mid_side_stereo(bool value);
bool set_loose_mid_side_stereo(bool value);
bool set_channels(unsigned value);
bool set_bits_per_sample(unsigned value);
bool set_sample_rate(unsigned value);
bool set_blocksize(unsigned value);
bool set_apodization(const char *specification);
bool set_max_lpc_order(unsigned value);
bool set_qlp_coeff_precision(unsigned value);
bool set_do_qlp_coeff_prec_search(bool value);
bool set_do_escape_coding(bool value);
bool set_do_exhaustive_model_search(bool value);
bool set_min_residual_partition_order(unsigned value);
bool set_max_residual_partition_order(unsigned value);
bool set_rice_parameter_search_dist(unsigned value);
bool set_total_samples_estimate(FLAC__uint64 value);
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks);
State get_state() const;
Stream::State get_stream_encoder_state() const;
Decoder::Stream::State get_verify_decoder_state() const;
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
bool get_verify() const;
bool get_streamable_subset() const;
bool get_do_mid_side_stereo() const;
bool get_loose_mid_side_stereo() const;
unsigned get_channels() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
unsigned get_max_lpc_order() const;
unsigned get_qlp_coeff_precision() const;
bool get_do_qlp_coeff_prec_search() const;
bool get_do_escape_coding() const;
bool get_do_exhaustive_model_search() const;
unsigned get_min_residual_partition_order() const;
unsigned get_max_residual_partition_order() const;
unsigned get_rice_parameter_search_dist() const;
FLAC__uint64 get_total_samples_estimate() const;
State init();
void finish();
bool process(const FLAC__int32 * const buffer[], unsigned samples);
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
protected:
virtual ::FLAC__SeekableStreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
virtual ::FLAC__SeekableStreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::FLAC__SeekableStreamEncoder *encoder_;
private:
static ::FLAC__SeekableStreamEncoderSeekStatus seek_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__SeekableStreamEncoderTellStatus tell_callback_(const FLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static ::FLAC__StreamEncoderWriteStatus write_callback_(const FLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
// Private and undefined so you can't use them:
SeekableStream(const SeekableStream &);
void operator=(const SeekableStream &);
};
/* \} */
/** \defgroup flacpp_file_encoder FLAC++/encoder.h: file encoder class
* \ingroup flacpp_encoder
*
* \brief
* This class wraps the ::FLAC__FileEncoder.
* This class wraps the ::FLAC__StreamEncoder.
*
* See the \link flac_file_encoder libFLAC file encoder module \endlink.
* See the \link flac_stream_encoder libFLAC stream encoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::FLAC__FileEncoder.
/** This class wraps the ::FLAC__StreamEncoder. If you are
* not encoding to a file, you may need to use
* FLAC::Encoder::Stream.
*
* The usage of this class is similar to FLAC__StreamEncoder,
* except instead of providing callbacks to
* FLAC__stream_encoder_init_FILE() or
* FLAC__stream_encoder_init_file(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call File::init(). The rest of
* the calls work the same as in the C layer.
*
* There are no mandatory callbacks; all the callbacks from
* FLAC::Encoder::Stream are implemented here fully and support
* full post-encode STREAMINFO and SEEKTABLE updating. There is
* only an optional progress callback which you may override to
* get periodic reports on the progress of the encode.
*/
class FLACPP_API File {
class FLACPP_API File: public Stream {
public:
class FLACPP_API State {
public:
inline State(::FLAC__FileEncoderState state): state_(state) { }
inline operator ::FLAC__FileEncoderState() const { return state_; }
inline const char *as_cstring() const { return ::FLAC__FileEncoderStateString[state_]; }
inline const char *resolved_as_cstring(const File &encoder) const { return ::FLAC__file_encoder_get_resolved_state_string(encoder.encoder_); }
protected:
::FLAC__FileEncoderState state_;
};
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See FLAC__stream_encoder_init_FILE() and
* FLAC__stream_encoder_init_file().
* \{
*/
File();
virtual ~File();
/* \} */
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_verify(bool value);
bool set_streamable_subset(bool value);
bool set_do_mid_side_stereo(bool value);
bool set_loose_mid_side_stereo(bool value);
bool set_channels(unsigned value);
bool set_bits_per_sample(unsigned value);
bool set_sample_rate(unsigned value);
bool set_blocksize(unsigned value);
bool set_apodization(const char *specification);
bool set_max_lpc_order(unsigned value);
bool set_qlp_coeff_precision(unsigned value);
bool set_do_qlp_coeff_prec_search(bool value);
bool set_do_escape_coding(bool value);
bool set_do_exhaustive_model_search(bool value);
bool set_min_residual_partition_order(unsigned value);
bool set_max_residual_partition_order(unsigned value);
bool set_rice_parameter_search_dist(unsigned value);
bool set_total_samples_estimate(FLAC__uint64 value);
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks);
bool set_filename(const char *value);
State get_state() const;
SeekableStream::State get_seekable_stream_encoder_state() const;
Stream::State get_stream_encoder_state() const;
Decoder::Stream::State get_verify_decoder_state() const;
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
bool get_verify() const;
bool get_streamable_subset() const;
bool get_do_mid_side_stereo() const;
bool get_loose_mid_side_stereo() const;
unsigned get_channels() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
unsigned get_max_lpc_order() const;
unsigned get_qlp_coeff_precision() const;
bool get_do_qlp_coeff_prec_search() const;
bool get_do_escape_coding() const;
bool get_do_exhaustive_model_search() const;
unsigned get_min_residual_partition_order() const;
unsigned get_max_residual_partition_order() const;
unsigned get_rice_parameter_search_dist() const;
FLAC__uint64 get_total_samples_estimate() const;
State init();
void finish();
bool process(const FLAC__int32 * const buffer[], unsigned samples);
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
::FLAC__StreamEncoderInitStatus init(FILE *file);
::FLAC__StreamEncoderInitStatus init(const char *filename);
::FLAC__StreamEncoderInitStatus init(const std::string &filename);
protected:
/// See FLAC__StreamEncoderProgressCallback
virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::FLAC__FileEncoder *encoder_;
/// This is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame);
private:
static void progress_callback_(const ::FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
static void progress_callback_(const ::FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
// Private and undefined so you can't use them:
File(const Stream &);

4
include/FLAC/Makefile.am
View File

@@ -35,12 +35,8 @@ flaccinclude_HEADERS = \
assert.h \
callback.h \
export.h \
file_decoder.h \
file_encoder.h \
format.h \
metadata.h \
ordinals.h \
seekable_stream_decoder.h \
seekable_stream_encoder.h \
stream_decoder.h \
stream_encoder.h

144
include/FLAC/all.h
View File

@@ -36,13 +36,9 @@
#include "assert.h"
#include "callback.h"
#include "file_decoder.h"
#include "file_encoder.h"
#include "format.h"
#include "metadata.h"
#include "ordinals.h"
#include "seekable_stream_decoder.h"
#include "seekable_stream_encoder.h"
#include "stream_decoder.h"
#include "stream_encoder.h"
@@ -121,6 +117,12 @@
* individual functions. You can see different views of the individual
* functions through the links in top bar across this page.
*
* \section porting_guide Porting Guide
*
* Starting with FLAC 1.1.3 a \link porting Porting Guide \endlink
* has been introduced which gives detailed instructions on how to
* port your code to newer versions of FLAC.
*
* \section embedded_developers Embedded Developers
*
* libFLAC has grown larger over time as more functionality has been
@@ -144,6 +146,140 @@
* will greatly reduce the size of the library.
*/
/** \defgroup porting Porting Guide for New Versions
*
* This module describes differences in the library interfaces from
* version to version. It assists in the porting of code that uses
* the libraries to newer versions of FLAC.
*/
/** \defgroup porting_1_1_2_to_1_1_3 Porting from FLAC 1.1.2 to 1.1.3
* \ingroup porting
*
* \brief
* This module describes porting from FLAC 1.1.2 to FLAC 1.1.3.
*
* The main change between the APIs in 1.1.2 and 1.1.3 is that the three
* decoding layers and three encoding layers have been merged into a
* single stream decoder and stream encoder. That is, the functionality
* of FLAC__SeekableStreamDecoder and FLAC__FileDecoder has been merged
* into FLAC__StreamDecoder, and FLAC__SeekableStreamEncoder and
* FLAC__FileEncoder into FLAC__StreamEncoder. Only the
* FLAC__StreamDecoder and FLAC__StreamEncoder remain. This can
* simplify code that needs to process both seekable and non-seekable
* streams.
*
* Instead of creating an encoder or decoder of a certain layer, now the
* client will always create a FLAC__StreamEncoder or
* FLAC__StreamDecoder. The different layers are differentiated by the
* initialization function. For example, for the decoder,
* FLAC__stream_decoder_init() has been replaced by
* FLAC__stream_decoder_init_stream(). This init function takes
* callbacks for the I/O, and the seeking callbacks are optional. This
* allows the client to use the same object for seekable and
* non-seekable streams. For decoding a FLAC file directly, the client
* can use FLAC__stream_decoder_init_file() and pass just a filename
* and fewer callbacks; most of the other callbacks are supplied
* internally. For situations where fopen()ing by filename is not
* possible (e.g. Unicode filenames on Windows) the client can instead
* open the file itself and supply the FILE* to
* FLAC__stream_decoder_init_FILE(). The init functions now returns a
* FLAC__StreamDecoderInitStatus instead of FLAC__StreamDecoderState.
* Since the callbacks and client data are now passed to the init
* function, the FLAC__stream_decoder_set_*_callback() functions and
* FLAC__stream_decoder_set_client_data() are no longer needed. The
* rest of the calls to the decoder are the same as before.
*
* As an example, in FLAC 1.1.2 a seekable stream decoder would be set
* up like so:
*@@@@@@CHECK@@@@@@
* \code
* FLAC__SeekableStreamDecoder *decoder = FLAC__seekable_stream_decoder_new();
* if(decoder == NULL) do something;
* FLAC__seekable_stream_decoder_set_md5_checking(decoder, true);
* [... other settings ...]
* FLAC__seekable_stream_decoder_set_read_callback(decoder, my_read_callback);
* FLAC__seekable_stream_decoder_set_seek_callback(decoder, my_seek_callback);
* FLAC__seekable_stream_decoder_set_tell_callback(decoder, my_tell_callback);
* FLAC__seekable_stream_decoder_set_length_callback(decoder, my_length_callback);
* FLAC__seekable_stream_decoder_set_eof_callback(decoder, my_eof_callback);
* FLAC__seekable_stream_decoder_set_write_callback(decoder, my_write_callback);
* FLAC__seekable_stream_decoder_set_metadata_callback(decoder, my_metadata_callback);
* FLAC__seekable_stream_decoder_set_error_callback(decoder, my_error_callback);
* FLAC__seekable_stream_decoder_set_client_data(decoder, my_client_data);
* if(FLAC__seekable_stream_decoder_init(decoder) != FLAC__SEEKABLE_STREAM_DECODER_OK) do something;
* \endcode
*
* In FLAC 1.1.3 it is like this:
*
* \code
* FLAC__StreamDecoder *decoder = FLAC__stream_decoder_new();
* if(decoder == NULL) do something;
* FLAC__stream_decoder_set_md5_checking(decoder, true);
* [... other settings ...]
* if(FLAC__stream_decoder_init_stream(
* decoder,
* my_read_callback,
* my_seek_callback, // or NULL
* my_tell_callback, // or NULL
* my_length_callback, // or NULL
* my_eof_callback, // or NULL
* my_write_callback,
* my_metadata_callback, // or NULL
* my_error_callback,
* my_client_data,
* ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do something;
* \endcode
*
* or you could do;
*
* \code
* [...]
* FILE *file = fopen("somefile.flac","rb");
* if(file == NULL) do somthing;
* if(FLAC__stream_decoder_init_FILE(
* decoder,
* file,
* my_write_callback,
* my_metadata_callback, // or NULL
* my_error_callback,
* my_client_data,
* ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do something;
* \endcode
*
* or just:
*
* \code
* [...]
* if(FLAC__stream_decoder_init_FILE(
* decoder,
* "somefile.flac",
* my_write_callback,
* my_metadata_callback, // or NULL
* my_error_callback,
* my_client_data,
* ) != FLAC__STREAM_DECODER_INIT_STATUS_OK) do something;
* \endcode
*
* Another small change to the decoder is in how it handles unparseable
* streams. Before, when the decoder found an unparseable stream
* (reserved for when the decoder encounters a stream from a future
* encoder that it can't parse), it changed the state to
* \c FLAC__STREAM_DECODER_UNPARSEABLE_STREAM. Now the decoder instead
* drops sync and calls the error callback with a new error code
* \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM. This is
* more robust. If your error callback does not discriminate on the the
* error state, your code does not need to be changed.
*
* The encoder now has a new setting:
* FLAC__stream_encoder_set_apodization(). This is for setting the
* method used to window the data before LPC analysis. You only need to
* add a call to this function if the default is not There are also
* two new convenience functions that may be useful:
* FLAC__metadata_object_cuesheet_calculate_cddb_id() and
* FLAC__metadata_get_cuesheet().
*/
/** \defgroup flac FLAC C API
*
* The FLAC C API is the interface to libFLAC, a set of structures

660
include/FLAC/file_decoder.h
View File

@@ -1,660 +0,0 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef FLAC__FILE_DECODER_H
#define FLAC__FILE_DECODER_H
#include "export.h"
#include "seekable_stream_decoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/file_decoder.h
*
* \brief
* This module contains the functions which implement the file
* decoder.
*
* See the detailed documentation in the
* \link flac_file_decoder file decoder \endlink module.
*/
/** \defgroup flac_file_decoder FLAC/file_decoder.h: file decoder interface
* \ingroup flac_decoder
*
* \brief
* 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
* FLAC__file_decoder_new().
* - The program overrides the default settings and sets callbacks for
* writing, error reporting, and metadata reporting using
* FLAC__file_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using FLAC__file_decoder_init().
* - The program calls the FLAC__file_decoder_process_*() functions
* to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with FLAC__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
* FLAC__file_decoder_delete().
*
* The file decoder is a trivial wrapper around the
* \link flac_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
* FLAC__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,
* FLAC__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 flac_seekable_stream_decoder seekable stream decoder module \endlink
* and \link flac_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 FLAC__FILE_DECODER_UNINITIALIZED, i.e. after
* FLAC__file_decoder_new() or FLAC__file_decoder_finish(), but
* before FLAC__file_decoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* FLAC__file_decoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
*
* \{
*/
/** State values for a FLAC__FileDecoder
*
* The decoder's state can be obtained by calling FLAC__file_decoder_get_state().
*/
typedef enum {
FLAC__FILE_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
FLAC__FILE_DECODER_END_OF_FILE,
/**< The decoder has reached the end of the file. */
FLAC__FILE_DECODER_ERROR_OPENING_FILE,
/**< An error occurred opening the input file. */
FLAC__FILE_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__FILE_DECODER_SEEK_ERROR,
/**< An error occurred while seeking. */
FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying seekable stream decoder. */
FLAC__FILE_DECODER_ALREADY_INITIALIZED,
/**< FLAC__file_decoder_init() was called when the decoder was already
* initialized, usually because FLAC__file_decoder_finish() was not
* called.
*/
FLAC__FILE_DECODER_INVALID_CALLBACK,
/**< FLAC__file_decoder_init() was called without all callbacks
* being set.
*/
FLAC__FILE_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} FLAC__FileDecoderState;
/** Maps a FLAC__FileDecoderState to a C string.
*
* Using a FLAC__FileDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__FileDecoderStateString[];
/***********************************************************************
*
* class FLAC__FileDecoder : public FLAC__StreamDecoder
*
***********************************************************************/
struct FLAC__FileDecoderProtected;
struct FLAC__FileDecoderPrivate;
/** The opaque structure definition for the file decoder type. See the
* \link flac_file_decoder file decoder module \endlink for a detailed
* description.
*/
typedef struct {
struct FLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileDecoder;
/** Signature for the write callback.
* See FLAC__file_decoder_set_write_callback()
* and FLAC__SeekableStreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame.
* \param buffer An array of pointers to decoded channels of data.
* \param client_data The callee's client data set through
* FLAC__file_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*FLAC__FileDecoderWriteCallback)(const FLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See FLAC__file_decoder_set_metadata_callback()
* and FLAC__SeekableStreamDecoderMetadataCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param metadata The decoded metadata block.
* \param client_data The callee's client data set through
* FLAC__file_decoder_set_client_data().
*/
typedef void (*FLAC__FileDecoderMetadataCallback)(const FLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See FLAC__file_decoder_set_error_callback()
* and FLAC__SeekableStreamDecoderErrorCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param status The error encountered by the decoder.
* \param client_data The callee's client data set through
* FLAC__file_decoder_set_client_data().
*/
typedef void (*FLAC__FileDecoderErrorCallback)(const FLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new file decoder instance. The instance is created with
* default settings; see the individual FLAC__file_decoder_set_*()
* functions for each setting's default.
*
* \retval FLAC__FileDecoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__FileDecoder *FLAC__file_decoder_new();
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
*
* \param decoder A pointer to an existing decoder.
* \assert
* \code decoder != NULL \endcode
*/
FLAC_API void FLAC__file_decoder_delete(FLAC__FileDecoder *decoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** 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.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_md5_checking(FLAC__FileDecoder *decoder, FLAC__bool value);
/** Set the input file name to decode.
*
* \default \c "-"
* \param decoder A decoder instance to set.
* \param value The input file name, or "-" for \c stdin.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, or there was a memory
* allocation error, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_filename(FLAC__FileDecoder *decoder, const char *value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_write_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderWriteCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderMetadataCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_error_callback(FLAC__FileDecoder *decoder, FLAC__FileDecoderErrorCallback value);
/** 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 decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_client_data(FLAC__FileDecoder *decoder, void *value);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_respond_all(FLAC__FileDecoder *decoder);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore(FLAC__FileDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_application(FLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_set_metadata_ignore_all(FLAC__FileDecoder *decoder);
/** Get the current decoder state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__FileDecoderState
* The current decoder state.
*/
FLAC_API FLAC__FileDecoderState FLAC__file_decoder_get_state(const FLAC__FileDecoder *decoder);
/** Get the state of the underlying seekable stream decoder.
* Useful when the file decoder state is
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__SeekableStreamDecoderState
* The seekable stream decoder state.
*/
FLAC_API FLAC__SeekableStreamDecoderState FLAC__file_decoder_get_seekable_stream_decoder_state(const FLAC__FileDecoder *decoder);
/** Get the state of the underlying stream decoder.
* Useful when the file decoder state is
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR and the seekable stream
* decoder state is \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The seekable stream decoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__file_decoder_get_stream_decoder_state(const FLAC__FileDecoder *decoder);
/** Get the current decoder state as a C string.
* This version automatically resolves
* \c FLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR by getting the
* seekable stream decoder's state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval const char *
* The decoder state as a C string. Do not modify the contents.
*/
FLAC_API const char *FLAC__file_decoder_get_resolved_state_string(const FLAC__FileDecoder *decoder);
/** Get the "MD5 signature checking" flag.
* This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_md5_checking().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_get_md5_checking(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_channels(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__ChannelAssignment
* See above.
*/
FLAC_API FLAC__ChannelAssignment FLAC__file_decoder_get_channel_assignment(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_bits_per_sample(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_sample_rate(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__file_decoder_get_blocksize(const FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_decode_position().
*
* \param decoder A decoder instance to query.
* \param position Address at which to return the desired position.
* \assert
* \code decoder != NULL \endcode
* \code position != NULL \endcode
* \retval FLAC__bool
* \c true if successful, \c false if there was an error from
* the 'tell' callback.
*/
FLAC_API FLAC__bool FLAC__file_decoder_get_decode_position(const FLAC__FileDecoder *decoder, FLAC__uint64 *position);
/** Initialize the decoder instance.
* Should be called after FLAC__file_decoder_new() and
* FLAC__file_decoder_set_*() but before any of the
* FLAC__file_decoder_process_*() functions. Will set and return
* the decoder state, which will be FLAC__FILE_DECODER_OK if
* initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__FileDecoderState
* \c FLAC__FILE_DECODER_OK if initialization was successful; see
* FLAC__FileDecoderState for the meanings of other return values.
*/
FLAC_API FLAC__FileDecoderState FLAC__file_decoder_init(FLAC__FileDecoder *decoder);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
* settings to their defaults, and returns the decoder state to
* FLAC__FILE_DECODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before FLAC__file_decoder_delete()
* but it is good practice to match every FLAC__file_decoder_init() with
* a FLAC__file_decoder_finish().
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if MD5 checking is on AND a STREAMINFO block was available
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
* signature does not match the one computed by the decoder; else
* \c true.
*/
FLAC_API FLAC__bool FLAC__file_decoder_finish(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_process_single(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_metadata(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_process_until_end_of_file(FLAC__FileDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_skip_single_frame().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__file_decoder_skip_single_frame(FLAC__FileDecoder *decoder);
/** Flush the input and seek to an absolute sample.
* 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.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false.
*/
FLAC_API FLAC__bool FLAC__file_decoder_seek_absolute(FLAC__FileDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

886
include/FLAC/file_encoder.h
View File

@@ -1,886 +0,0 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef FLAC__FILE_ENCODER_H
#define FLAC__FILE_ENCODER_H
#include "export.h"
#include "seekable_stream_encoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/file_encoder.h
*
* \brief
* This module contains the functions which implement the file
* encoder.
*
* See the detailed documentation in the
* \link flac_file_encoder file encoder \endlink module.
*/
/** \defgroup flac_file_encoder FLAC/file_encoder.h: file encoder interface
* \ingroup flac_encoder
*
* \brief
* 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
* FLAC__file_encoder_new().
* - The program overrides the default settings using
* FLAC__file_encoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for encoding using FLAC__file_encoder_init().
* - The program calls FLAC__file_encoder_process() or
* FLAC__file_encoder_process_interleaved() to encode data, which
* subsequently writes data to the output file.
* - The program finishes the encoding with FLAC__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
* FLAC__file_encoder_delete().
*
* The file encoder is a wrapper around the
* \link flac_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 flac_seekable_stream_encoder seekable stream encoder module \endlink since the
* \link flac_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 FLAC__FILE_ENCODER_UNINITIALIZED, i.e. after
* FLAC__file_encoder_new() or FLAC__file_encoder_finish(), but
* before FLAC__file_encoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* FLAC__file_encoder_finish() resets all settings to the constructor
* defaults.
*
* \{
*/
/** State values for a FLAC__FileEncoder
*
* The encoder's state can be obtained by calling FLAC__file_encoder_get_state().
*/
typedef enum {
FLAC__FILE_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
FLAC__FILE_ENCODER_NO_FILENAME,
/**< FLAC__file_encoder_init() was called without first calling
* FLAC__file_encoder_set_filename().
*/
FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying seekable stream encoder;
* check FLAC__file_encoder_get_seekable_stream_encoder_state().
*/
FLAC__FILE_ENCODER_FATAL_ERROR_WHILE_WRITING,
/**< A fatal error occurred while writing to the encoded file. */
FLAC__FILE_ENCODER_ERROR_OPENING_FILE,
/**< An error occurred opening the output file for writing. */
FLAC__FILE_ENCODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
FLAC__FILE_ENCODER_ALREADY_INITIALIZED,
/**< FLAC__file_encoder_init() was called when the encoder was
* already initialized, usually because
* FLAC__file_encoder_finish() was not called.
*/
FLAC__FILE_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
} FLAC__FileEncoderState;
/** Maps a FLAC__FileEncoderState to a C string.
*
* Using a FLAC__FileEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__FileEncoderStateString[];
/***********************************************************************
*
* class FLAC__FileEncoder
*
***********************************************************************/
struct FLAC__FileEncoderProtected;
struct FLAC__FileEncoderPrivate;
/** The opaque structure definition for the file encoder type.
* See the \link flac_file_encoder file encoder module \endlink
* for a detailed description.
*/
typedef struct {
struct FLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__FileEncoder;
/** Signature for the progress callback.
* See FLAC__file_encoder_set_progress_callback() for more info.
*
* \param encoder The encoder instance calling the callback.
* \param bytes_written Bytes written so far.
* \param samples_written Samples written so far.
* \param frames_written Frames written so far.
* \param total_frames_estimate The estimate of the total number of
* frames to be written.
* \param client_data The callee's client data set through
* FLAC__file_encoder_set_client_data().
*/
typedef void (*FLAC__FileEncoderProgressCallback)(const FLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new file encoder instance. The instance is created with
* default settings; see the individual FLAC__file_encoder_set_*()
* functions for each setting's default.
*
* \retval FLAC__FileEncoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__FileEncoder *FLAC__file_encoder_new();
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
*
* \param encoder A pointer to an existing encoder.
* \assert
* \code encoder != NULL \endcode
*/
FLAC_API void FLAC__file_encoder_delete(FLAC__FileEncoder *encoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_verify().
*
* \default \c true
* \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_API FLAC__bool FLAC__file_encoder_set_verify(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_streamable_subset().
*
* \default \c true
* \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_API FLAC__bool FLAC__file_encoder_set_streamable_subset(FLAC__FileEncoder *encoder, FLAC__bool value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_do_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_loose_mid_side_stereo(FLAC__FileEncoder *encoder, FLAC__bool value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_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_API FLAC__bool FLAC__file_encoder_set_channels(FLAC__FileEncoder *encoder, unsigned value);
/** 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
* set here or you will generate an invalid stream.
*
* \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_API FLAC__bool FLAC__file_encoder_set_bits_per_sample(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_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_API FLAC__bool FLAC__file_encoder_set_sample_rate(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_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_API FLAC__bool FLAC__file_encoder_set_blocksize(FLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_set_apodization().
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param specification See above.
* \assert
* \code encoder != NULL \endcode
* \code specification != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
/* @@@@add to unit tests*/
FLAC_API FLAC__bool FLAC__file_encoder_set_apodization(FLAC__FileEncoder *encoder, const char *specification);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_max_lpc_order(FLAC__FileEncoder *encoder, unsigned value);
/** 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
* be less than 32.
*
* \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_API FLAC__bool FLAC__file_encoder_set_qlp_coeff_precision(FLAC__FileEncoder *encoder, unsigned value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_do_qlp_coeff_prec_search(FLAC__FileEncoder *encoder, FLAC__bool value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_do_escape_coding(FLAC__FileEncoder *encoder, FLAC__bool value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_do_exhaustive_model_search(FLAC__FileEncoder *encoder, FLAC__bool value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_min_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_max_residual_partition_order(FLAC__FileEncoder *encoder, unsigned value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_rice_parameter_search_dist(FLAC__FileEncoder *encoder, unsigned value);
/** 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.
* \param value See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_total_samples_estimate(FLAC__FileEncoder *encoder, FLAC__uint64 value);
/** This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_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_API FLAC__bool FLAC__file_encoder_set_metadata(FLAC__FileEncoder *encoder, FLAC__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 FLAC__FileDecoder, the filename does not interpret "-" for
* \c stdout; writing to \c stdout is not relevant in the file encoder.
*
* \default \c NULL
* \param encoder A encoder instance to set.
* \param value The output file name.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, or there was a memory
* allocation error, else \c true.
*/
FLAC_API FLAC__bool FLAC__file_encoder_set_filename(FLAC__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
* FLAC__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.
*
* \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_API FLAC__bool FLAC__file_encoder_set_progress_callback(FLAC__FileEncoder *encoder, FLAC__FileEncoderProgressCallback value);
/** 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_API FLAC__bool FLAC__file_encoder_set_client_data(FLAC__FileEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__FileEncoderState
* The current encoder state.
*/
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_get_state(const FLAC__FileEncoder *encoder);
/** Get the state of the underlying seekable stream encoder.
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__SeekableStreamEncoderState
* The seekable stream encoder state.
*/
FLAC_API FLAC__SeekableStreamEncoderState FLAC__file_encoder_get_seekable_stream_encoder_state(const FLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder.
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the 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 FLAC__StreamEncoderState
* The seekable stream encoder state.
*/
FLAC_API FLAC__StreamEncoderState FLAC__file_encoder_get_stream_encoder_state(const FLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder's verify decoder.
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the 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 stream encoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__file_encoder_get_verify_decoder_state(const FLAC__FileEncoder *encoder);
/** Get the current encoder state as a C string.
* This version automatically resolves
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the
* seekable stream encoder's state.
*
* \param encoder A encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval const char *
* The encoder state as a C string. Do not modify the contents.
*/
FLAC_API const char *FLAC__file_encoder_get_resolved_state_string(const FLAC__FileEncoder *encoder);
/** Get relevant values about the nature of a verify decoder error.
* Inherited from FLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
* Useful when the file encoder state is
* \c FLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR and the 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.
* \param absolute_sample The absolute sample number of the mismatch.
* \param frame_number The number of the frame in which the mismatch occurred.
* \param channel The channel in which the mismatch occurred.
* \param sample The number of the sample (relative to the frame) in
* which the mismatch occurred.
* \param expected The expected value for the sample in question.
* \param got The actual value returned by the decoder.
* \assert
* \code encoder != NULL \endcode
*/
FLAC_API void FLAC__file_encoder_get_verify_decoder_error_stats(const FLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
/** Get the "verify" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_verify().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_verify().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_verify(const FLAC__FileEncoder *encoder);
/** Get the "streamable subset" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_streamable_subset().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_streamable_subset().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_streamable_subset(const FLAC__FileEncoder *encoder);
/** Get the "mid/side stereo coding" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_get_do_mid_side_stereo().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_mid_side_stereo(const FLAC__FileEncoder *encoder);
/** Get the "adaptive mid/side switching" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_loose_mid_side_stereo().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_loose_mid_side_stereo().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_loose_mid_side_stereo(const FLAC__FileEncoder *encoder);
/** Get the number of input channels being processed.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_channels().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_channels().
*/
FLAC_API unsigned FLAC__file_encoder_get_channels(const FLAC__FileEncoder *encoder);
/** Get the input sample resolution setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_bits_per_sample().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_bits_per_sample().
*/
FLAC_API unsigned FLAC__file_encoder_get_bits_per_sample(const FLAC__FileEncoder *encoder);
/** Get the input sample rate setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_sample_rate().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_sample_rate().
*/
FLAC_API unsigned FLAC__file_encoder_get_sample_rate(const FLAC__FileEncoder *encoder);
/** Get the blocksize setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_blocksize().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_blocksize().
*/
FLAC_API unsigned FLAC__file_encoder_get_blocksize(const FLAC__FileEncoder *encoder);
/** Get the maximum LPC order setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_max_lpc_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_max_lpc_order().
*/
FLAC_API unsigned FLAC__file_encoder_get_max_lpc_order(const FLAC__FileEncoder *encoder);
/** Get the quantized linear predictor coefficient precision setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_qlp_coeff_precision().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_qlp_coeff_precision().
*/
FLAC_API unsigned FLAC__file_encoder_get_qlp_coeff_precision(const FLAC__FileEncoder *encoder);
/** Get the qlp coefficient precision search flag.
* 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
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_do_qlp_coeff_prec_search().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_qlp_coeff_prec_search(const FLAC__FileEncoder *encoder);
/** Get the "escape coding" flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_escape_coding().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_do_escape_coding().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_escape_coding(const FLAC__FileEncoder *encoder);
/** Get the exhaustive model search flag.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_do_exhaustive_model_search().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See FLAC__file_encoder_set_do_exhaustive_model_search().
*/
FLAC_API FLAC__bool FLAC__file_encoder_get_do_exhaustive_model_search(const FLAC__FileEncoder *encoder);
/** Get the minimum residual partition order setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_min_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_min_residual_partition_order().
*/
FLAC_API unsigned FLAC__file_encoder_get_min_residual_partition_order(const FLAC__FileEncoder *encoder);
/** Get maximum residual partition order setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_max_residual_partition_order().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_max_residual_partition_order().
*/
FLAC_API unsigned FLAC__file_encoder_get_max_residual_partition_order(const FLAC__FileEncoder *encoder);
/** Get the Rice parameter search distance setting.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_rice_parameter_search_dist().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_rice_parameter_search_dist().
*/
FLAC_API unsigned FLAC__file_encoder_get_rice_parameter_search_dist(const FLAC__FileEncoder *encoder);
/** Get the previously set estimate of the total samples to be encoded.
* This is inherited from FLAC__SeekableStreamEncoder; see
* FLAC__seekable_stream_encoder_get_total_samples_estimate().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__uint64
* See FLAC__file_encoder_set_total_samples_estimate().
*/
FLAC_API FLAC__uint64 FLAC__file_encoder_get_total_samples_estimate(const FLAC__FileEncoder *encoder);
/** Initialize the encoder instance.
* Should be called after FLAC__file_encoder_new() and
* FLAC__file_encoder_set_*() but before FLAC__file_encoder_process()
* or FLAC__file_encoder_process_interleaved(). Will set and return
* the encoder state, which will be FLAC__FILE_ENCODER_OK if
* initialization succeeded.
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__FileEncoderState
* \c FLAC__FILE_ENCODER_OK if initialization was successful; see
* FLAC__FileEncoderState for the meanings of other return values.
*/
FLAC_API FLAC__FileEncoderState FLAC__file_encoder_init(FLAC__FileEncoder *encoder);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to
* FLAC__FILE_ENCODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated encode, it is not strictly
* necessary to call this immediately before FLAC__file_encoder_delete()
* but it is good practice to match every FLAC__file_encoder_init()
* with a FLAC__file_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
*/
FLAC_API void FLAC__file_encoder_finish(FLAC__FileEncoder *encoder);
/** Submit data for encoding.
* 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.
* \param samples The number of samples in one channel.
* \assert
* \code encoder != NULL \endcode
* \code FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with FLAC__file_encoder_get_state() to see what
* went wrong.
*/
FLAC_API FLAC__bool FLAC__file_encoder_process(FLAC__FileEncoder *encoder, const FLAC__int32 * const buffer[], unsigned samples);
/** Submit data for encoding.
* 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).
* \param samples The number of samples in one channel, the same as for
* FLAC__file_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 FLAC__file_encoder_get_state(encoder) == FLAC__FILE_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with FLAC__file_encoder_get_state() to see what
* went wrong.
*/
FLAC_API FLAC__bool FLAC__file_encoder_process_interleaved(FLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

29
include/FLAC/metadata.h
View File

@@ -1338,11 +1338,40 @@ FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_points(FLAC_
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \code total_samples > 0 \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points(FLAC__StreamMetadata *object, unsigned num, FLAC__uint64 total_samples);
/** Append a set of evenly-spaced seek point templates to the end of a
* seek table.
*
* \note
* As with the other ..._seektable_template_... functions, you should
* call FLAC__metadata_object_seektable_template_sort() when finished
* to make the seek table legal.
*
* \param object A pointer to an existing SEEKTABLE object.
* \param samples The number of samples apart to space the placeholder
* points. The first point will be at sample \c 0, the
* second at sample \a samples, then 2*\a samples, and
* so on. As long as \a samples and \a total_samples
* are greater than \c 0, there will always be at least
* one seekpoint at sample \0.
* \param total_samples The total number of samples to be encoded;
* the seekpoints will be spaced
* \a samples samples apart.
* \assert
* \code object != NULL \endcode
* \code object->type == FLAC__METADATA_TYPE_SEEKTABLE \endcode
* \code samples > 0 \endcode
* \code total_samples > 0 \endcode
* \retval FLAC__bool
* \c false if memory allocation fails, else \c true.
*/
FLAC_API FLAC__bool FLAC__metadata_object_seektable_template_append_spaced_points_by_samples(FLAC__StreamMetadata *object, unsigned samples, FLAC__uint64 total_samples);
/** Sort a seek table's seek points according to the format specification,
* removing duplicates.
*

931
include/FLAC/seekable_stream_decoder.h
View File

@@ -1,931 +0,0 @@
/* libFLAC - Free Lossless Audio Codec library
* Copyright (C) 2000,2001,2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef FLAC__SEEKABLE_STREAM_DECODER_H
#define FLAC__SEEKABLE_STREAM_DECODER_H
#include "export.h"
#include "stream_decoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/FLAC/seekable_stream_decoder.h
*
* \brief
* This module contains the functions which implement the seekable stream
* decoder.
*
* See the detailed documentation in the
* \link flac_seekable_stream_decoder seekable stream decoder \endlink module.
*/
/** \defgroup flac_seekable_stream_decoder FLAC/seekable_stream_decoder.h: seekable stream decoder interface
* \ingroup flac_decoder
*
* \brief
* 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
* FLAC__seekable_stream_decoder_new().
* - The program overrides the default settings and sets callbacks for
* reading, writing, seeking, error reporting, and metadata reporting
* using FLAC__seekable_stream_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using FLAC__seekable_stream_decoder_init().
* - The program calls the FLAC__seekable_stream_decoder_process_*()
* functions to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with
* FLAC__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
* FLAC__seekable_stream_decoder_delete().
*
* The seekable stream decoder is a wrapper around the
* \link flac_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
* FLAC__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,
* FLAC__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
* FLAC__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 flac_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 FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED, i.e. after
* FLAC__seekable_stream_decoder_new() or
* FLAC__seekable_stream_decoder_finish(), but before
* FLAC__seekable_stream_decoder_init(). If this is the case they will
* return \c true, otherwise \c false.
*
* \note
* FLAC__stream_decoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
*
* \{
*/
/** State values for a FLAC__SeekableStreamDecoder
*
* The decoder's state can be obtained by calling FLAC__seekable_stream_decoder_get_state().
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_OK = 0,
/**< The decoder is in the normal OK state. */
FLAC__SEEKABLE_STREAM_DECODER_SEEKING,
/**< The decoder is in the process of seeking. */
FLAC__SEEKABLE_STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
FLAC__SEEKABLE_STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying stream decoder. */
FLAC__SEEKABLE_STREAM_DECODER_READ_ERROR,
/**< The read callback returned an error. */
FLAC__SEEKABLE_STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking or the seek or tell
* callback returned an error.
*/
FLAC__SEEKABLE_STREAM_DECODER_ALREADY_INITIALIZED,
/**< FLAC__seekable_stream_decoder_init() was called when the
* decoder was already initialized, usually because
* FLAC__seekable_stream_decoder_finish() was not called.
*/
FLAC__SEEKABLE_STREAM_DECODER_INVALID_CALLBACK,
/**< FLAC__seekable_stream_decoder_init() was called without all
* callbacks being set.
*/
FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} FLAC__SeekableStreamDecoderState;
/** Maps a FLAC__SeekableStreamDecoderState to a C string.
*
* Using a FLAC__SeekableStreamDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderStateString[];
/** Return values for the FLAC__SeekableStreamDecoder read callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_OK,
/**< The read was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_READ_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderReadStatus;
/** Maps a FLAC__SeekableStreamDecoderReadStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderReadStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderReadStatusString[];
/** Return values for the FLAC__SeekableStreamDecoder seek callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_OK,
/**< The seek was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_SEEK_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderSeekStatus;
/** Maps a FLAC__SeekableStreamDecoderSeekStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderSeekStatusString[];
/** Return values for the FLAC__SeekableStreamDecoder tell callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_OK,
/**< The tell was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_TELL_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderTellStatus;
/** Maps a FLAC__SeekableStreamDecoderTellStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderTellStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderTellStatusString[];
/** Return values for the FLAC__SeekableStreamDecoder length callback.
*/
typedef enum {
FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_OK,
/**< The length call was OK and decoding can continue. */
FLAC__SEEKABLE_STREAM_DECODER_LENGTH_STATUS_ERROR
/**< An unrecoverable error occurred. The decoder will return from the process call. */
} FLAC__SeekableStreamDecoderLengthStatus;
/** Maps a FLAC__SeekableStreamDecoderLengthStatus to a C string.
*
* Using a FLAC__SeekableStreamDecoderLengthStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__SeekableStreamDecoderLengthStatusString[];
/***********************************************************************
*
* class FLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
*
***********************************************************************/
struct FLAC__SeekableStreamDecoderProtected;
struct FLAC__SeekableStreamDecoderPrivate;
/** The opaque structure definition for the seekable stream decoder type.
* See the
* \link flac_seekable_stream_decoder seekable stream decoder module \endlink
* for a detailed description.
*/
typedef struct {
struct FLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct FLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} FLAC__SeekableStreamDecoder;
/** Signature for the read callback.
* See FLAC__seekable_stream_decoder_set_read_callback()
* and FLAC__StreamDecoderReadCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param buffer A pointer to a location for the callee to store
* data to be decoded.
* \param bytes A pointer to the size of the buffer.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderReadStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderReadStatus (*FLAC__SeekableStreamDecoderReadCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the seek callback.
* See FLAC__seekable_stream_decoder_set_seek_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param absolute_byte_offset The offset from the beginning of the stream
* to seek to.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderSeekStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderSeekStatus (*FLAC__SeekableStreamDecoderSeekCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
* See FLAC__seekable_stream_decoder_set_tell_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param absolute_byte_offset A pointer to storage for the current offset
* from the beginning of the stream.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderTellStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderTellStatus (*FLAC__SeekableStreamDecoderTellCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the length callback.
* See FLAC__seekable_stream_decoder_set_length_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param stream_length A pointer to storage for the length of the stream
* in bytes.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderLengthStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamDecoderLengthStatus (*FLAC__SeekableStreamDecoderLengthCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
/** Signature for the EOF callback.
* See FLAC__seekable_stream_decoder_set_eof_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__bool
* \c true if the currently at the end of the stream, else \c false.
*/
typedef FLAC__bool (*FLAC__SeekableStreamDecoderEofCallback)(const FLAC__SeekableStreamDecoder *decoder, void *client_data);
/** Signature for the write callback.
* See FLAC__seekable_stream_decoder_set_write_callback()
* and FLAC__StreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame.
* \param buffer An array of pointers to decoded channels of data.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*FLAC__SeekableStreamDecoderWriteCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See FLAC__seekable_stream_decoder_set_metadata_callback()
* and FLAC__StreamDecoderMetadataCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param metadata The decoded metadata block.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
*/
typedef void (*FLAC__SeekableStreamDecoderMetadataCallback)(const FLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See FLAC__seekable_stream_decoder_set_error_callback()
* and FLAC__StreamDecoderErrorCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param status The error encountered by the decoder.
* \param client_data The callee's client data set through
* FLAC__seekable_stream_decoder_set_client_data().
*/
typedef void (*FLAC__SeekableStreamDecoderErrorCallback)(const FLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new seekable stream decoder instance. The instance is created
* with default settings; see the individual
* FLAC__seekable_stream_decoder_set_*() functions for each setting's
* default.
*
* \retval FLAC__SeekableStreamDecoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
FLAC_API FLAC__SeekableStreamDecoder *FLAC__seekable_stream_decoder_new();
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
*
* \param decoder A pointer to an existing decoder.
* \assert
* \code decoder != NULL \endcode
*/
FLAC_API void FLAC__seekable_stream_decoder_delete(FLAC__SeekableStreamDecoder *decoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** 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 FLAC__seekable_stream_decoder_finish().
*
* MD5 signature checking will be turned off (until the next
* FLAC__seekable_stream_decoder_reset()) if there is no signature in
* the STREAMINFO block or when a seek is attempted.
*
* \default \c false
* \param decoder A decoder instance to set.
* \param value Flag value (see above).
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_md5_checking(FLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
/** Set the read callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_read_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_read_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_seek_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_tell_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_length_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__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.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_eof_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderEofCallback value);
/** Set the write callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_write_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_write_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_metadata_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_set_error_callback().
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_error_callback(FLAC__SeekableStreamDecoder *decoder, FLAC__SeekableStreamDecoderErrorCallback value);
/** 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 decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_client_data(FLAC__SeekableStreamDecoder *decoder, void *value);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_respond_all(FLAC__SeekableStreamDecoder *decoder);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore(FLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_application(FLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_set_metadata_ignore_all(FLAC__SeekableStreamDecoder *decoder);
/** Get the current decoder state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__SeekableStreamDecoderState
* The current decoder state.
*/
FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_get_state(const FLAC__SeekableStreamDecoder *decoder);
/** Get the state of the underlying stream decoder.
* Useful when the seekable stream decoder state is
* \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The stream decoder state.
*/
FLAC_API FLAC__StreamDecoderState FLAC__seekable_stream_decoder_get_stream_decoder_state(const FLAC__SeekableStreamDecoder *decoder);
/** Get the current decoder state as a C string.
* This version automatically resolves
* \c FLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR by getting the
* stream decoder's state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval const char *
* The decoder state as a C string. Do not modify the contents.
*/
FLAC_API const char *FLAC__seekable_stream_decoder_get_resolved_state_string(const FLAC__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.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_md5_checking(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_channels(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__ChannelAssignment
* See above.
*/
FLAC_API FLAC__ChannelAssignment FLAC__seekable_stream_decoder_get_channel_assignment(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_bits_per_sample(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_sample_rate(const FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API unsigned FLAC__seekable_stream_decoder_get_blocksize(const FLAC__SeekableStreamDecoder *decoder);
/** Returns the decoder's current read position within the stream.
* The position is the byte offset from the start of the stream.
* Bytes before this position have been fully decoded. Note that
* there may still be undecoded bytes in the decoder's read FIFO.
* The returned position is correct even after a seek.
*
* \param decoder A decoder instance to query.
* \param position Address at which to return the desired position.
* \assert
* \code decoder != NULL \endcode
* \code position != NULL \endcode
* \retval FLAC__bool
* \c true if successful, \c false if there was an error from
* the 'tell' callback.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_get_decode_position(const FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *position);
/** Initialize the decoder instance.
* Should be called after FLAC__seekable_stream_decoder_new() and
* FLAC__seekable_stream_decoder_set_*() but before any of the
* FLAC__seekable_stream_decoder_process_*() functions. Will set and return
* the decoder state, which will be FLAC__SEEKABLE_STREAM_DECODER_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__SeekableStreamDecoderState
* \c FLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
* successful; see FLAC__SeekableStreamDecoderState for the meanings
* of other return values.
*/
FLAC_API FLAC__SeekableStreamDecoderState FLAC__seekable_stream_decoder_init(FLAC__SeekableStreamDecoder *decoder);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
* settings to their defaults, and returns the decoder state to
* FLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before
* FLAC__seekable_stream_decoder_delete() but it is good practice to match
* every FLAC__seekable_stream_decoder_init() with a
* FLAC__seekable_stream_decoder_finish().
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if MD5 checking is on AND a STREAMINFO block was available
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
* signature does not match the one computed by the decoder; else
* \c true.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_finish(FLAC__SeekableStreamDecoder *decoder);
/** Flush the stream input.
* The decoder's input buffer will be cleared and the state set to
* \c FLAC__SEEKABLE_STREAM_DECODER_OK. This will also turn off MD5
* checking.
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* or stream decoder error occurs.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_flush(FLAC__SeekableStreamDecoder *decoder);
/** Reset the decoding process.
* The decoder's input buffer will be cleared and the state set to
* \c FLAC__SEEKABLE_STREAM_DECODER_OK. This is similar to
* FLAC__seekable_stream_decoder_finish() except that the settings are
* preserved; there is no need to call FLAC__seekable_stream_decoder_init()
* before decoding again. MD5 checking will be restored to its original
* setting.
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* or stream decoder error occurs.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_reset(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_single(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_metadata(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_process_until_end_of_stream(FLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see
* FLAC__stream_decoder_skip_single_frame().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_skip_single_frame(FLAC__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.
*
* \param decoder A decoder instance.
* \param sample The target sample number to seek to.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false.
*/
FLAC_API FLAC__bool FLAC__seekable_stream_decoder_seek_absolute(FLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

1007
include/FLAC/seekable_stream_encoder.h
View File

File diff suppressed because it is too large Load Diff

744
include/FLAC/stream_decoder.h
View File

@@ -32,6 +32,7 @@
#ifndef FLAC__STREAM_DECODER_H
#define FLAC__STREAM_DECODER_H
#include <stdio.h> /* for FILE */
#include "export.h"
#include "format.h"
@@ -54,24 +55,22 @@ extern "C" {
* \ingroup flac
*
* \brief
* This module describes the three decoder layers provided by libFLAC.
* This module describes the two decoder layers provided by libFLAC.
*
* For decoding FLAC streams, libFLAC provides three layers of access. The
* lowest layer is non-seekable stream-level decoding, the next is seekable
* stream-level decoding, and the highest layer is file-level decoding. The
* interfaces are described in the \link flac_stream_decoder stream decoder
* \endlink, \link flac_seekable_stream_decoder seekable stream decoder
* \endlink, and \link flac_file_decoder file decoder \endlink modules
* respectively. Typically you will choose the highest layer that your input
* source will support.
* libFLAC provides two ways of decoding FLAC streams. There is a @@@@@@frame decoder which decodes single frames at a time, and a stream decoder which decodes whole streams.
*
* 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.
* @@@@@@TODO frame decoder
*
* The stream decoder can be used decode complete streams either from the
* client via callbacks, or directly from a file, depending on how it is
* initialized. When decoding via callbacks, the client provides
* callbacks for reading FLAC data and writing decoded samples, and
* handling metadata and errors. If the client also supplies seek-related
* callback, the decoder function for sample-accurate seeking within the
* FLAC input is also available. When decoding from a file, the client
* needs only supply a filename or open \c FILE* and write/metadata/error
* callbacks; the rest of the callbacks are supplied internally. For more
* info see the \link flac_stream_decoder stream decoder \endlink module.
*/
/** \defgroup flac_stream_decoder FLAC/stream_decoder.h: stream decoder interface
@@ -84,11 +83,12 @@ extern "C" {
* The basic usage of this decoder is as follows:
* - The program creates an instance of a decoder using
* FLAC__stream_decoder_new().
* - The program overrides the default settings and sets callbacks for
* reading, writing, error reporting, and metadata reporting using
* - The program overrides the default settings using
* FLAC__stream_decoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for decoding using FLAC__stream_decoder_init().
* prepare for decoding using FLAC__stream_decoder_init() or
* FLAC__stream_decoder_init_FILE() or FLAC__stream_decoder_init_file(),
* depending on the nature of the input.
* - The program calls the FLAC__stream_decoder_process_*() functions
* to decode data, which subsequently calls the callbacks.
* - The program finishes the decoding with FLAC__stream_decoder_finish(),
@@ -99,33 +99,21 @@ extern "C" {
*
* In more detail, the program will create a new instance by calling
* FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*()
* functions to set the callbacks and client data, and call
* FLAC__stream_decoder_init(). The required callbacks are:
* functions to override the default decoder options, and call
* on of the FLAC__stream_decoder_init_*() functions.
*
* - Read callback - This function will be called when the decoder needs
* more input data. The address of the buffer to be filled is supplied,
* along with the number of bytes the buffer can hold. The callback may
* choose to supply less data and modify the byte count but must be careful
* not to overflow the buffer. The callback then returns a status code
* chosen from FLAC__StreamDecoderReadStatus.
* - Write callback - This function will be called when the decoder has
* decoded a single frame of data. The decoder will pass the frame
* metadata as well as an array of pointers (one for each channel)
* pointing to the decoded audio.
* - Metadata callback - This function will be called when the decoder has
* decoded a metadata block. In a valid FLAC file there will always be
* one STREAMINFO block, followed by zero or more other metadata
* blocks. These will be supplied by the decoder in the same order as
* they appear in the stream and always before the first audio frame
* (i.e. write callback). The metadata block that is passed in must not
* be modified, and it doesn't live beyond the callback, so you should
* make a copy of it with FLAC__metadata_object_clone() if you will need
* it elsewhere. Since metadata blocks can potentially be large, by
* default the decoder only calls the metadata callback for the STREAMINFO
* block; you can instruct the decoder to pass or filter other blocks with
* FLAC__stream_decoder_set_metadata_*() calls.
* - Error callback - This function will be called whenever an error occurs
* during decoding.
* There are three initialization functions, one for setting up the decoder
* to decode FLAC data from the client via callbacks, and two for decoding
* directly from a FLAC file.
*
* For decoding via callbacks, use FLAC__stream_decoder_init_stream().
* You must also supply several callbacks for handling I/O. Some (like
* seeking) are optional, depending on the capabilities of the input.
*
* For decoding directly from a file, use FLAC__stream_decoder_init_FILE()
* or FLAC__stream_decoder_init_file(). Then you must only supply a
* filename or open \c FILE* and fewer callbacks; the decoder will handle
* the other callbacks internally.
*
* Once the decoder is initialized, your program will call one of several
* functions to start the decoding process:
@@ -151,11 +139,23 @@ extern "C" {
* instance may be deleted with FLAC__stream_decoder_delete() or initialized
* again to decode another stream.
*
* Note that the stream decoder has no real concept of stream position, it
* just converts data. To seek within a stream the callbacks have only to
* flush the decoder using FLAC__stream_decoder_flush() and start feeding
* data from the new position through the read callback. The seekable
* stream decoder does just this.
* Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method.
* At any point after the 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.
*
* If the client cannot seek via the callback interface provided, but still
* has another way of seeking, it can flush the decoder using
* FLAC__stream_decoder_flush() and start feeding data from the new position
* through the read callback.
*
* The stream decoder also provides MD5 signature checking. If this is
* turned on before initialization, FLAC__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 FLAC__stream_decoder_reset()) if there is no signature
* in the STREAMINFO block or when a seek is attempted.
*
* The FLAC__stream_decoder_set_metadata_*() functions deserve special
* attention. By default, the decoder only calls the metadata_callback for
@@ -191,7 +191,7 @@ extern "C" {
/** State values for a FLAC__StreamDecoder
*
* The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
* The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().
*/
typedef enum {
@@ -202,7 +202,9 @@ typedef enum {
/**< The decoder is ready to or is in the process of reading metadata. */
FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC,
/**< The decoder is ready to or is in the process of searching for the frame sync code. */
/**< The decoder is ready to or is in the process of searching for the
* frame sync code.
*/
FLAC__STREAM_DECODER_READ_FRAME,
/**< The decoder is ready to or is in the process of reading a frame. */
@@ -210,23 +212,25 @@ typedef enum {
FLAC__STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
FLAC__STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking. The decoder must be flushed
* with FLAC__stream_decoder_flush() or reset with
* FLAC__stream_decoder_reset() before decoding can continue.
*/
FLAC__STREAM_DECODER_ABORTED,
/**< The decoder was aborted by the read callback. */
FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__STREAM_DECODER_ALREADY_INITIALIZED,
/**< FLAC__stream_decoder_init() was called when the decoder was
* already initialized, usually because
* FLAC__stream_decoder_finish() was not called.
/**< An error occurred allocating memory. The decoder is in an invalid
* state and can no longer be used.
*/
FLAC__STREAM_DECODER_INVALID_CALLBACK,
/**< FLAC__stream_decoder_init() was called without all callbacks being set. */
FLAC__STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
/**< The decoder is in the uninitialized state; one of the
* FLAC__stream_decoder_init_*() functions must be called before samples
* can be processed.
*/
} FLAC__StreamDecoderState;
@@ -238,6 +242,38 @@ typedef enum {
extern FLAC_API const char * const FLAC__StreamDecoderStateString[];
/** Possible return values for the FLAC__stream_decoder_init_*() functions.
*/
typedef enum {
FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
/**< Initialization was successful. */
FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
/**< A required callback was not supplied. */
FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE,
/**< fopen() failed in FLAC__stream_decoder_init_file(). */
FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED
/**< FLAC__stream_decoder_init_*() was called when the decoder was
* already initialized, usually because
* FLAC__stream_decoder_finish() was not called.
*/
} FLAC__StreamDecoderInitStatus;
/** Maps a FLAC__StreamDecoderInitStatus to a C string.
*
* Using a FLAC__StreamDecoderInitStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamDecoderInitStatusString[];
/** Return values for the FLAC__StreamDecoder read callback.
*/
typedef enum {
@@ -246,7 +282,15 @@ typedef enum {
/**< The read was OK and decoding can continue. */
FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM,
/**< The read was attempted at the end of the stream. */
/**< The read was attempted while at the end of the stream. Note that
* the client must only return this value when the read callback was
* called when already at the end of the stream. Otherwise, if the read
* itself moves to the end of the stream, the client should still return
* the data and \c FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on
* the next read callback it should return
* \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count
* of \c 0.
*/
FLAC__STREAM_DECODER_READ_STATUS_ABORT
/**< An unrecoverable error occurred. The decoder will return from the process call. */
@@ -261,6 +305,75 @@ typedef enum {
extern FLAC_API const char * const FLAC__StreamDecoderReadStatusString[];
/** Return values for the FLAC__StreamDecoder seek callback.
*/
typedef enum {
FLAC__STREAM_DECODER_SEEK_STATUS_OK,
/**< The seek was OK and decoding can continue. */
FLAC__STREAM_DECODER_SEEK_STATUS_ERROR,
/**< An unrecoverable error occurred. The decoder will return from the process call. */
FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
/**< Client does not support seeking. */
} FLAC__StreamDecoderSeekStatus;
/** Maps a FLAC__StreamDecoderSeekStatus to a C string.
*
* Using a FLAC__StreamDecoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamDecoderSeekStatusString[];
/** Return values for the FLAC__StreamDecoder tell callback.
*/
typedef enum {
FLAC__STREAM_DECODER_TELL_STATUS_OK,
/**< The tell was OK and decoding can continue. */
FLAC__STREAM_DECODER_TELL_STATUS_ERROR,
/**< An unrecoverable error occurred. The decoder will return from the process call. */
FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
/**< Client does not support telling the position. */
} FLAC__StreamDecoderTellStatus;
/** Maps a FLAC__StreamDecoderTellStatus to a C string.
*
* Using a FLAC__StreamDecoderTellStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamDecoderTellStatusString[];
/** Return values for the FLAC__StreamDecoder length callback.
*/
typedef enum {
FLAC__STREAM_DECODER_LENGTH_STATUS_OK,
/**< The length call was OK and decoding can continue. */
FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR,
/**< An unrecoverable error occurred. The decoder will return from the process call. */
FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
/**< Client does not support reporting the length. */
} FLAC__StreamDecoderLengthStatus;
/** Maps a FLAC__StreamDecoderLengthStatus to a C string.
*
* Using a FLAC__StreamDecoderLengthStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamDecoderLengthStatusString[];
/** Return values for the FLAC__StreamDecoder write callback.
*/
typedef enum {
@@ -338,7 +451,18 @@ typedef struct {
} FLAC__StreamDecoder;
/** Signature for the read callback.
* See FLAC__stream_decoder_set_read_callback() for more info.
*
* A function pointer matching this signature must be passed to
* FLAC__stream_decoder_init_stream(). The supplied function will be
* called when the decoder needs more input data. The address of the
* buffer to be filled is supplied, along with the number of bytes the
* buffer can hold. The callback may choose to supply less data and
* modify the byte count but must be careful not to overflow the buffer.
* The callback then returns a status code chosen from
* FLAC__StreamDecoderReadStatus.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param buffer A pointer to a location for the callee to store
@@ -350,14 +474,103 @@ typedef struct {
* stored (0 in case of error or end-of-stream) before
* returning.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_set_client_data().
* FLAC__stream_decoder_init_*().
* \retval FLAC__StreamDecoderReadStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the seek callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_decoder_init_stream(). 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.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param absolute_byte_offset The offset from the beginning of the stream
* to seek to.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_init_*().
* \retval FLAC__StreamDecoderSeekStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderSeekStatus (*FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_decoder_init_stream(). 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.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param absolute_byte_offset A pointer to storage for the current offset
* from the beginning of the stream.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_init_*().
* \retval FLAC__StreamDecoderTellStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderTellStatus (*FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the length callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_decoder_init_stream(). The supplied function will be
* called when the decoder wants to know the total length of the stream
* in bytes.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param stream_length A pointer to storage for the length of the stream
* in bytes.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_init_*().
* \retval FLAC__StreamDecoderLengthStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderLengthStatus (*FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
/** Signature for the EOF callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_decoder_init_stream(). The supplied function will be
* called when the decoder needs to know if the end of the stream has
* been reached.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_init_*().
* \retval FLAC__bool
* \c true if the currently at the end of the stream, else \c false.
*/
typedef FLAC__bool (*FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data);
/** Signature for the write callback.
* See FLAC__stream_decoder_set_write_callback() for more info.
*
* A function pointer matching this signature must be passed to one of
* the FLAC__stream_decoder_init_*() functions.
* The supplied function will be called when the decoder has decoded a
* single audio frame. The decoder will pass the frame metadata as well
* as an array of pointers (one for each channel) pointing to the
* decoded audio.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame. See
@@ -369,29 +582,53 @@ typedef FLAC__StreamDecoderReadStatus (*FLAC__StreamDecoderReadCallback)(const F
* except for stereo streams; in this case channel
* 0 is left and 1 is right.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_set_client_data().
* FLAC__stream_decoder_init_*().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See FLAC__stream_decoder_set_metadata_callback() for more info.
*
* A function pointer matching this signature must be passed to one of
* the FLAC__stream_decoder_init_*() functions.
* The supplied function will be called when the decoder has decoded a
* metadata block. In a valid FLAC file there will always be one
* \c STREAMINFO block, followed by zero or more other metadata blocks.
* These will be supplied by the decoder in the same order as they
* appear in the stream and always before the first audio frame (i.e.
* write callback). The metadata block that is passed in must not be
* modified, and it doesn't live beyond the callback, so you should make
* a copy of it with FLAC__metadata_object_clone() if you will need it
* elsewhere. Since metadata blocks can potentially be large, by
* default the decoder only calls the metadata callback for the
* \c STREAMINFO block; you can instruct the decoder to pass or filter
* other blocks with FLAC__stream_decoder_set_metadata_*() calls.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param metadata The decoded metadata block.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_set_client_data().
* FLAC__stream_decoder_init_*().
*/
typedef void (*FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See FLAC__stream_decoder_set_error_callback() for more info.
*
* A function pointer matching this signature must be passed to one of
* the FLAC__stream_decoder_init_*() functions.
* The supplied function will be called whenever an error occurs during
* decoding.
*
* \note In general, FLAC__StreamDecoder functions which change the
* state should not be called on the \a decoder while in the callback.
*
* \param decoder The decoder instance calling the callback.
* \param status The error encountered by the decoder.
* \param client_data The callee's client data set through
* FLAC__stream_decoder_set_client_data().
* FLAC__stream_decoder_init_*().
*/
typedef void (*FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
@@ -426,107 +663,27 @@ FLAC_API void FLAC__stream_decoder_delete(FLAC__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 FLAC__StreamDecoderReadStatus.
/** 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 FLAC__stream_decoder_finish().
*
* \note
* The callback is mandatory and must be set before initialization.
* MD5 signature checking will be turned off (until the next
* FLAC__stream_decoder_reset()) if there is no signature in the
* STREAMINFO block or when a seek is attempted.
*
* \default \c NULL
* Clients that do not use the MD5 check should leave this off to speed
* up decoding.
*
* \default \c false
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback value);
/** Set the write callback.
* The supplied function will be called when the decoder has decoded a
* single frame of data. The decoder will pass the frame metadata as
* well as an array of pointers (one for each channel) pointing to the
* decoded audio.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_write_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderWriteCallback value);
/** Set the metadata callback.
* The supplied function will be called when the decoder has decoded a metadata
* block. In a valid FLAC file there will always be one STREAMINFO block,
* followed by zero or more other metadata blocks. These will be supplied
* by the decoder in the same order as they appear in the stream and always
* before the first audio frame (i.e. write callback). The metadata block
* that is passed in must not be modified, and it doesn't live beyond the
* callback, so you should make a copy of it with
* FLAC__metadata_object_clone() if you will need it elsewhere. Since
* metadata blocks can potentially be large, by default the decoder only
* calls the metadata callback for the STREAMINFO block; you can instruct
* the decoder to pass or filter other blocks with
* FLAC__stream_decoder_set_metadata_*() calls.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_metadata_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderMetadataCallback value);
/** Set the error callback.
* The supplied function will be called whenever an error occurs during
* decoding.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_error_callback(FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorCallback value);
/** 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 decoder A decoder instance to set.
* \param value See above.
* \param value Flag value (see above).
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_client_data(FLAC__StreamDecoder *decoder, void *value);
FLAC_API FLAC__bool FLAC__stream_decoder_set_md5_checking(FLAC__StreamDecoder *decoder, FLAC__bool value);
/** Direct the decoder to pass on all metadata blocks of type \a type.
*
@@ -630,6 +787,32 @@ FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_get_state(const FLAC__Str
*/
FLAC_API const char *FLAC__stream_decoder_get_resolved_state_string(const FLAC__StreamDecoder *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.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_get_md5_checking(const FLAC__StreamDecoder *decoder);
/** Get the total number of samples in the stream being decoded.
* Will only be valid after decoding has started and will contain the
* value from the \c STREAMINFO block. A value of \c 0 means "unknown".
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
FLAC_API FLAC__uint64 FLAC__stream_decoder_get_total_samples(const FLAC__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.
@@ -690,22 +873,187 @@ FLAC_API unsigned FLAC__stream_decoder_get_sample_rate(const FLAC__StreamDecoder
*/
FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *decoder);
/** Returns the decoder's current read position within the stream.
* The position is the byte offset from the start of the stream.
* Bytes before this position have been fully decoded. Note that
* there may still be undecoded bytes in the decoder's read FIFO.
* The returned position is correct even after a seek.
*
* \param decoder A decoder instance to query.
* \param position Address at which to return the desired position.
* \assert
* \code decoder != NULL \endcode
* \code position != NULL \endcode
* \retval FLAC__bool
* \c true if successful, \c false if there was an error from
* the 'tell' callback or it returned
* \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_get_decode_position(const FLAC__StreamDecoder *decoder, FLAC__uint64 *position);
/** Initialize the decoder instance.
* Should be called after FLAC__stream_decoder_new() and
*
* This flavor of initialization sets up the decoder to decode from a stream.
* I/O is performed via callbacks to the client. For decoding from a plain file
* via filename or open FILE*, FLAC__stream_decoder_init_file() and
* FLAC__stream_decoder_init_FILE() provide a simpler interface.
*
* This function should be called after FLAC__stream_decoder_new() and
* FLAC__stream_decoder_set_*() but before any of the
* FLAC__stream_decoder_process_*() functions. Will set and return the
* decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \param decoder An uninitialized decoder instance.
* \param read_callback See FLAC__StreamDecoderReadCallback. This
* pointer must not be \c NULL.
* \param seek_callback See FLAC__StreamDecoderSeekCallback. This
* pointer may be \c NULL if seeking is not
* supported. If \a seek_callback is not \c NULL then a
* \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
* Alternatively, a dummy seek callback that just
* returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param tell_callback See FLAC__StreamDecoderTellCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy tell callback that just
* returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param length_callback See FLAC__StreamDecoderLengthCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a length_callback must also be supplied.
* Alternatively, a dummy length callback that just
* returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param eof_callback See FLAC__StreamDecoderEofCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a eof_callback must also be supplied.
* Alternatively, a dummy length callback that just
* returns \c false
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA if initialization was
* successful; see FLAC__StreamDecoderState for the meanings of other
* return values.
* \retval FLAC__StreamDecoderInitStatus
* \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamDecoderInitStatus for the meanings of other return values.
*/
FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder *decoder);
FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
FLAC__StreamDecoder *decoder,
FLAC__StreamDecoderReadCallback read_callback,
FLAC__StreamDecoderSeekCallback seek_callback,
FLAC__StreamDecoderTellCallback tell_callback,
FLAC__StreamDecoderLengthCallback length_callback,
FLAC__StreamDecoderEofCallback eof_callback,
FLAC__StreamDecoderWriteCallback write_callback,
FLAC__StreamDecoderMetadataCallback metadata_callback,
FLAC__StreamDecoderErrorCallback error_callback,
void *client_data
);
/** Initialize the decoder instance.
*
* This flavor of initialization sets up the decoder to decode from a plain
* file. For non-stdio streams, you must use
* FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
*
* This function should be called after FLAC__stream_decoder_new() and
* FLAC__stream_decoder_set_*() but before any of the
* FLAC__stream_decoder_process_*() functions. Will set and return the
* decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \param file An open FLAC file. The file should have been
* opened with mode \c "rb" and rewound. The file
* becomes owned by the decoder and should not be
* manipulated by the client while decoding.
* Unless \a file is \c stdin, it will be closed
* when FLAC__stream_decoder_finish() is called.
* Note however that seeking will not work when
* decoding from \c stdout since it is not seekable.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code decoder != NULL \endcode
* \code file != NULL \endcode
* \retval FLAC__StreamDecoderInitStatus
* \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamDecoderInitStatus for the meanings of other return values.
*/
FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE(
FLAC__StreamDecoder *decoder,
FILE *file,
FLAC__StreamDecoderWriteCallback write_callback,
FLAC__StreamDecoderMetadataCallback metadata_callback,
FLAC__StreamDecoderErrorCallback error_callback,
void *client_data
);
/** Initialize the decoder instance.
*
* This flavor of initialization sets up the decoder to decode from a plain
* file. If POSIX fopen() semantics are not sufficient, (for example, with
* Unicode filenames on Windows), you must use
* FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream()
* and provide callbacks for the I/O.
*
* This function should be called after FLAC__stream_decoder_new() and
* FLAC__stream_decoder_set_*() but before any of the
* FLAC__stream_decoder_process_*() functions. Will set and return the
* decoder state, which will be FLAC__STREAM_DECODER_SEARCH_FOR_METADATA
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \param filename The name of the file to decode from. The file will
* be opened with fopen(). Use \c NULL to decode from
* \c stdin. Note that \c stdin is not seekable.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderInitStatus
* \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamDecoderInitStatus for the meanings of other return values.
*/
FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file(
FLAC__StreamDecoder *decoder,
const char *filename,
FLAC__StreamDecoderWriteCallback write_callback,
FLAC__StreamDecoderMetadataCallback metadata_callback,
FLAC__StreamDecoderErrorCallback error_callback,
void *client_data
);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
@@ -720,19 +1068,26 @@ FLAC_API FLAC__StreamDecoderState FLAC__stream_decoder_init(FLAC__StreamDecoder
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if MD5 checking is on AND a STREAMINFO block was available
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
* signature does not match the one computed by the decoder; else
* \c true.
*/
FLAC_API void FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
FLAC_API FLAC__bool FLAC__stream_decoder_finish(FLAC__StreamDecoder *decoder);
/** Flush the stream input.
* The decoder's input buffer will be cleared and the state set to
* \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
* \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. This will also turn
* off MD5 checking.
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* error occurs.
* error occurs (in which case the state will be set to
* \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
*/
FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
@@ -741,14 +1096,31 @@ FLAC_API FLAC__bool FLAC__stream_decoder_flush(FLAC__StreamDecoder *decoder);
* \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to
* FLAC__stream_decoder_finish() except that the settings are
* preserved; there is no need to call FLAC__stream_decoder_init()
* before decoding again.
* before decoding again. MD5 checking will be restored to its original
* setting.
*
* If the decoder is seekable, or was initialized with
* FLAC__stream_decoder_init_FILE() or FLAC__stream_decoder_init_file(),
* the decoder will also attempt to seek to the beginning of the file.
* If this rewind fails, this function will return \c false. It follows
* that FLAC__stream_decoder_reset() cannot be used when decoding from
* \c stdin.
*
* If the decoder was initialized with FLAC__stream_encoder_init_stream()
* and is not seekable (i.e. no seek callback was provided or the seek
* callback returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it
* is the duty of the client to start feeding data from the beginning of
* the stream on the next FLAC__stream_decoder_process() or
* FLAC__stream_decoder_process_interleaved() call.
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* error occurs.
* \c true if successful, else \c false if a memory allocation occurs
* (in which case the state will be set to
* \c FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error
* occurs (the state will be unchanged).
*/
FLAC_API FLAC__bool FLAC__stream_decoder_reset(FLAC__StreamDecoder *decoder);
@@ -869,6 +1241,24 @@ FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__Strea
*/
FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *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. The
* client must support seeking the input or this function will fail
* and return \c false. Furthermore, if the decoder state is
* \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed
* with FLAC__stream_decoder_flush() or reset with
* FLAC__stream_decoder_reset() before decoding can continue.
*
* \param decoder A decoder instance.
* \param sample The target sample number to seek to.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_seek_absolute(FLAC__StreamDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus

649
include/FLAC/stream_encoder.h
View File

@@ -32,6 +32,7 @@
#ifndef FLAC__STREAM_ENCODER_H
#define FLAC__STREAM_ENCODER_H
#include <stdio.h> /* for FILE */
#include "export.h"
#include "format.h"
#include "stream_decoder.h"
@@ -55,29 +56,23 @@ extern "C" {
* \ingroup flac
*
* \brief
* This module describes the three encoder layers provided by libFLAC.
* This module describes the two encoder layers provided by libFLAC.
*
* For encoding FLAC streams, libFLAC provides three layers of access. The
* lowest layer is non-seekable stream-level encoding, the next is seekable
* stream-level encoding, and the highest layer is file-level encoding. The
* interfaces are described in the \link flac_stream_encoder stream encoder
* \endlink, \link flac_seekable_stream_encoder seekable stream encoder
* \endlink, and \link flac_file_encoder file encoder \endlink modules
* respectively. Typically you will choose the highest layer that your input
* source will support.
* The stream encoder relies on callbacks for writing the data and
* metadata. The file encoder provides these callbacks internally and you
* need only supply the filename.
* libFLAC provides two ways of encoding FLAC streams. There is a @@@@@@frame encoder which encodes single frames at a time, and a stream encoder which encodes whole streams.
*
* The stream encoder relies on callbacks for writing the data and has no
* provisions for seeking the output. The seekable stream encoder wraps
* the stream encoder and also automaticallay handles the writing back of
* metadata discovered while encoding. However, you must provide extra
* callbacks for seek-related operations on your output, like seek and
* tell. The file encoder wraps the seekable stream encoder and supplies
* all of the callbacks internally, simplifying the processing of standard
* files. The only callback exposed is for progress reporting, and that
* is optional.
* @@@@@@TODO frame encoder
*
* The stream encoder can be used encode complete streams either to the
* client via callbacks, or directly to a file, depending on how it is
* initialized. When encoding via callbacks, the client provides a write
* callback which will be called whenever FLAC data is ready to be written.
* If the client also supplies a seek callback, the encoder will also
* automatically handle the writing back of metadata discovered while
* encoding, like stream info, seek points offsets, etc. When encoding to
* a file, the client needs only supply a filename or open \c FILE* and an
* optional progress callback for periodic notification of progress; the
* write and seek callbacks are supplied internally. For more info see the
* \link flac_stream_encoder stream encoder \endlink module.
*/
/** \defgroup flac_stream_encoder FLAC/stream_encoder.h: stream encoder interface
@@ -90,18 +85,21 @@ extern "C" {
* The basic usage of this encoder is as follows:
* - The program creates an instance of an encoder using
* FLAC__stream_encoder_new().
* - The program overrides the default settings and sets callbacks using
* - The program overrides the default settings using
* FLAC__stream_encoder_set_*() functions.
* - The program initializes the instance to validate the settings and
* prepare for encoding using FLAC__stream_encoder_init().
* prepare for encoding using FLAC__stream_encoder_init_stream() or
* FLAC__stream_encoder_init_FILE() or FLAC__stream_encoder_init_file(),
* depending on the nature of the output.
* - The program calls FLAC__stream_encoder_process() or
* FLAC__stream_encoder_process_interleaved() to encode data, which
* subsequently calls the callbacks when there is encoder data ready
* to be written.
* - The program finishes the encoding with FLAC__stream_encoder_finish(),
* which causes the encoder to encode any data still in its input pipe,
* call the metadata callback with the final encoding statistics, and
* finally reset the encoder to the uninitialized state.
* update the metadata with the final encoding statistics if output
* seeking is possible, and finally reset the encoder to the
* uninitialized state.
* - The instance may be used again or deleted with
* FLAC__stream_encoder_delete().
*
@@ -109,8 +107,9 @@ extern "C" {
* \link flac_stream_decoder stream decoder \endlink, but has fewer
* callbacks and more options. Typically the user will create a new
* instance by calling FLAC__stream_encoder_new(), then set the necessary
* parameters and callbacks with FLAC__stream_encoder_set_*(), and
* initialize it by calling FLAC__stream_encoder_init().
* parameters with FLAC__stream_encoder_set_*(), and initialize it by
* calling FLAC__stream_encoder_init_stream() or
* FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
*
* Unlike the decoders, the stream encoder has many options that can
* affect the speed and compression ratio. When setting these parameters
@@ -118,26 +117,32 @@ extern "C" {
* <A HREF="../documentation.html#format">user-level documentation</A>
* or the <A HREF="../format.html">formal description</A>). The
* FLAC__stream_encoder_set_*() functions themselves do not validate the
* values as many are interdependent. The FLAC__stream_encoder_init()
* function will do this, so make sure to pay attention to the state
* returned by FLAC__stream_encoder_init() to make sure that it is
* FLAC__STREAM_ENCODER_OK. Any parameters that are not set before
* FLAC__stream_encoder_init() will take on the defaults from the
* constructor.
* values as many are interdependent. The FLAC__stream_encoder_init_*()
* functions will do this, so make sure to pay attention to the state
* returned by FLAC__stream_encoder_init_*() to make sure that it is
* FLAC__STREAM_ENCODER_INIT_STATUS_OK. Any parameters that are not set
* before FLAC__stream_encoder_init_*() will take on the defaults from
* the constructor.
*
* The user must provide function pointers for the following callbacks:
* There are three initialization functions, one for setting up the encoder
* to encode FLAC data to the client via callbacks, and two for encoding
* directly to a file.
*
* - Write callback - This function is called by the encoder anytime there
* is raw encoded data to write. It may include metadata mixed with
* encoded audio frames and the data is not guaranteed to be aligned on
* frame or metadata block boundaries.
* - Metadata callback - This function is called once at the end of
* encoding with the populated STREAMINFO structure. This is so file
* encoders can seek back to the beginning of the file and write the
* STREAMINFO block with the correct statistics after encoding (like
* minimum/maximum frame size).
* For encoding via callbacks, use FLAC__stream_encoder_init_stream().
* You must also supply a write callback which will be called anytime
* there is raw encoded data to write. If the client can seek the output
* it is best to also supply seek and tell callbacks, as this allows the
* encoder to go back after encoding is finished to write back
* information that was collected while encoding, like seek point offsets,
* frame sizes, etc.
*
* The call to FLAC__stream_encoder_init() currently will also immediately
* For encoding directly to a file, use FLAC__stream_encoder_init_FILE()
* or FLAC__stream_encoder_init_file(). Then you must only supply a
* filename or open \c FILE*; the encoder will handle all the callbacks
* internally. You may also supply a progress callback for periodic
* notification of the encoding progress.
*
* The call to FLAC__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.
*
@@ -177,6 +182,14 @@ extern "C" {
* for the specification of metadata blocks and their lengths.
*
* \note
* If you are writing the FLAC data to a file via callbacks, make sure it
* is open for update (e.g. mode "w+" for stdio streams). This is because
* after the first encoding pass, the encoder will try to seek back to the
* beginning of the stream, to the STREAMINFO block, to write some data
* there. (If using FLAC__stream_encoder_init_file() or
* FLAC__stream_encoder_init_FILE(), the file is managed internally.)
*
* \note
* The "set" functions may only be called when the encoder is in the
* state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after
* FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but
@@ -185,20 +198,30 @@ extern "C" {
*
* \note
* FLAC__stream_encoder_finish() resets all settings to the constructor
* defaults, including the callbacks.
* defaults.
*
* \{
*/
/** State values for a FLAC__StreamEncoder
/** State values for a FLAC__StreamEncoder.
*
* The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
* The encoder's state can be obtained by calling FLAC__stream_encoder_get_state().
*
* If the encoder gets into any other state besides \c FLAC__STREAM_ENCODER_OK
* or \c FLAC__STREAM_ENCODER_UNINITIALIZED, it becomes invalid for encoding and
* must be deleted with FLAC__stream_encoder_delete().
*/
typedef enum {
FLAC__STREAM_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
/**< The encoder is in the normal OK state and samples can be processed. */
FLAC__STREAM_ENCODER_UNINITIALIZED,
/**< The encoder is in the uninitialized state; one of the
* FLAC__stream_encoder_init_*() functions must be called before samples
* can be processed.
*/
FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR,
/**< An error occurred in the underlying verify stream decoder;
@@ -210,75 +233,22 @@ typedef enum {
* audio signal and the decoded audio signal.
*/
FLAC__STREAM_ENCODER_INVALID_CALLBACK,
/**< The encoder was initialized before setting all the required callbacks. */
FLAC__STREAM_ENCODER_CLIENT_ERROR,
/**< One of the callbacks returned a fatal error. */
FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS,
/**< The encoder has an invalid setting for number of channels. */
FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE,
/**< The encoder has an invalid setting for bits-per-sample.
* FLAC supports 4-32 bps but the reference encoder currently supports
* only up to 24 bps.
FLAC__STREAM_ENCODER_IO_ERROR,
/**< An I/O error occurred while opening/reading/writing a file.
* Check \c errno.
*/
FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE,
/**< The encoder has an invalid setting for the input sample rate. */
FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE,
/**< The encoder has an invalid setting for the block size. */
FLAC__STREAM_ENCODER_INVALID_MAX_LPC_ORDER,
/**< The encoder has an invalid setting for the maximum LPC order. */
FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION,
/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH,
/**< Mid/side coding was specified but the number of channels is not equal to 2. */
FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH,
/**< Deprecated. */
FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE,
/**< Loose mid/side coding was specified but mid/side coding was not. */
FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
/**< The specified block size is less than the maximum LPC order. */
FLAC__STREAM_ENCODER_NOT_STREAMABLE,
/**< The encoder is bound to the "streamable subset" but other settings violate it. */
FLAC__STREAM_ENCODER_FRAMING_ERROR,
/**< An error occurred while writing the stream; usually, the write_callback returned an error. */
FLAC__STREAM_ENCODER_INVALID_METADATA,
/**< The metadata input to the encoder is invalid, in one of the following ways:
* - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
* - One of the metadata blocks contains an undefined type
* - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
* - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
* - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
/**< An error occurred while writing the stream; usually, the
* write_callback returned an error.
*/
FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING,
/**< An error occurred while writing the stream; usually, the write_callback returned an error. */
FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING,
/**< The write_callback returned an error. */
FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
/**< Memory allocation failed. */
FLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
/**< FLAC__stream_encoder_init() was called when the encoder was
* already initialized, usually because
* FLAC__stream_encoder_finish() was not called.
*/
FLAC__STREAM_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
} FLAC__StreamEncoderState;
/** Maps a FLAC__StreamEncoderState to a C string.
@@ -288,6 +258,79 @@ typedef enum {
*/
extern FLAC_API const char * const FLAC__StreamEncoderStateString[];
/** Possible return values for the FLAC__stream_encoder_init_*() functions.
*/
typedef enum {
FLAC__STREAM_ENCODER_INIT_STATUS_OK = 0,
/**< Initialization was successful. */
FLAC__STREAM_ENCODER_INIT_STATUS_ENCODER_ERROR,
/**< General failure to set up encoder; call FLAC__stream_encoder_get_state() for cause. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_CALLBACKS,
/**< A required callback was not supplied. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_NUMBER_OF_CHANNELS,
/**< The encoder has an invalid setting for number of channels. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BITS_PER_SAMPLE,
/**< The encoder has an invalid setting for bits-per-sample.
* FLAC supports 4-32 bps but the reference encoder currently supports
* only up to 24 bps.
*/
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_SAMPLE_RATE,
/**< The encoder has an invalid setting for the input sample rate. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_BLOCK_SIZE,
/**< The encoder has an invalid setting for the block size. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_MAX_LPC_ORDER,
/**< The encoder has an invalid setting for the maximum LPC order. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_QLP_COEFF_PRECISION,
/**< The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. */
FLAC__STREAM_ENCODER_INIT_STATUS_MID_SIDE_CHANNELS_MISMATCH,
/**< Mid/side coding was specified but the number of channels is not equal to 2. */
FLAC__STREAM_ENCODER_INIT_STATUS_MID_SIDE_SAMPLE_SIZE_MISMATCH,
/**< Deprecated. */
FLAC__STREAM_ENCODER_INIT_STATUS_ILLEGAL_MID_SIDE_FORCE,
/**< Loose mid/side coding was specified but mid/side coding was not. */
FLAC__STREAM_ENCODER_INIT_STATUS_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER,
/**< The specified block size is less than the maximum LPC order. */
FLAC__STREAM_ENCODER_INIT_STATUS_NOT_STREAMABLE,
/**< The encoder is bound to the "streamable subset" but other settings violate it. */
FLAC__STREAM_ENCODER_INIT_STATUS_INVALID_METADATA,
/**< The metadata input to the encoder is invalid, in one of the following ways:
* - FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0
* - One of the metadata blocks contains an undefined type
* - It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal()
* - It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal()
* - It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block
*/
FLAC__STREAM_ENCODER_INIT_STATUS_ALREADY_INITIALIZED
/**< FLAC__stream_encoder_init_*() was called when the encoder was
* already initialized, usually because
* FLAC__stream_encoder_finish() was not called.
*/
} FLAC__StreamEncoderInitStatus;
/** Maps a FLAC__StreamEncoderInitStatus to a C string.
*
* Using a FLAC__StreamEncoderInitStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamEncoderInitStatusString[];
/** Return values for the FLAC__StreamEncoder write callback.
*/
typedef enum {
@@ -307,6 +350,51 @@ typedef enum {
*/
extern FLAC_API const char * const FLAC__StreamEncoderWriteStatusString[];
/** Return values for the FLAC__StreamEncoder seek callback.
*/
typedef enum {
FLAC__STREAM_ENCODER_SEEK_STATUS_OK,
/**< The seek was OK and encoding can continue. */
FLAC__STREAM_ENCODER_SEEK_STATUS_ERROR,
/**< An unrecoverable error occurred. */
FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
/**< Client does not support seeking. */
} FLAC__StreamEncoderSeekStatus;
/** Maps a FLAC__StreamEncoderSeekStatus to a C string.
*
* Using a FLAC__StreamEncoderSeekStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamEncoderSeekStatusString[];
/** Return values for the FLAC__StreamEncoder tell callback.
*/
typedef enum {
FLAC__STREAM_ENCODER_TELL_STATUS_OK,
/**< The tell was OK and encoding can continue. */
FLAC__STREAM_ENCODER_TELL_STATUS_ERROR,
/**< An unrecoverable error occurred. */
FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
/**< Client does not support seeking. */
} FLAC__StreamEncoderTellStatus;
/** Maps a FLAC__StreamEncoderTellStatus to a C string.
*
* Using a FLAC__StreamEncoderTellStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern FLAC_API const char * const FLAC__StreamEncoderTellStatusString[];
/***********************************************************************
*
@@ -326,32 +414,126 @@ typedef struct {
} FLAC__StreamEncoder;
/** Signature for the write callback.
* See FLAC__stream_encoder_set_write_callback() for more info.
*
* A function pointer matching this signature must be passed to
* FLAC__stream_encoder_init_stream(). The supplied function will be called
* by the encoder anytime there is raw encoded data ready to write. It may
* include metadata mixed with encoded audio frames and the data is not
* guaranteed to be aligned on frame or metadata block boundaries.
*
* The only duty of the callback is to write out the \a bytes worth of data
* in \a buffer to the current position in the output stream. The arguments
* \a samples and \a current_frame are purely informational. If \a samples
* is greater than \c 0, then \a current_frame will hold the current frame
* number that is being written; otherwise it indicates that the write
* callback is being called to write metadata.
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
* \param encoder The encoder instance calling the callback.
* \param buffer An array of encoded data of length \a bytes.
* \param bytes The byte length of \a buffer.
* \param samples The number of samples encoded by \a buffer.
* \c 0 has a special meaning; see
* FLAC__stream_encoder_set_write_callback().
* \c 0 has a special meaning; see above.
* \param current_frame The number of the current frame being encoded.
* \param client_data The callee's client data set through
* FLAC__stream_encoder_set_client_data().
* FLAC__stream_encoder_init_*().
* \retval FLAC__StreamEncoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamEncoderWriteStatus (*FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
/** Signature for the seek callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_encoder_init_stream(). The supplied function will be called
* when the encoder needs to seek the output stream. The encoder will pass
* the absolute byte offset to seek to, 0 meaning the beginning of the stream.
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
* \param encoder The encoder instance calling the callback.
* \param absolute_byte_offset The offset from the beginning of the stream
* to seek to.
* \param client_data The callee's client data set through
* FLAC__stream_encoder_init_*().
* \retval FLAC__StreamEncoderSeekStatus
* The callee's return status.
*/
typedef FLAC__StreamEncoderSeekStatus (*FLAC__StreamEncoderSeekCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_encoder_init_stream(). The supplied function will be called
* when the encoder needs to know the current position of the output stream.
*
* \warning
* The callback must return the true current byte offset of the output to
* which the encoder is writing. If you are buffering the output, make
* sure and take this into account. If you are writing directly to a
* FILE* from your write callback, ftell() is sufficient. If you are
* writing directly to a file descriptor from your write callback, you
* can use lseek(fd, SEEK_CUR, 0). The encoder may later seek back to
* these points to rewrite metadata after encoding.
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
* \param encoder The encoder instance calling the callback.
* \param absolute_byte_offset The address at which to store the current
* position of the output.
* \param client_data The callee's client data set through
* FLAC__stream_encoder_init_*().
* \retval FLAC__StreamEncoderTellStatus
* The callee's return status.
*/
typedef FLAC__StreamEncoderTellStatus (*FLAC__StreamEncoderTellCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the metadata callback.
* See FLAC__stream_encoder_set_metadata_callback() for more info.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_encoder_init_stream(). The supplied function will be called
* once at the end of encoding with the populated STREAMINFO structure. This
* is so the client can seek back to the beginning of the file and write the
* STREAMINFO block with the correct statistics after encoding (like
* minimum/maximum frame size and total samples).
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
* \param encoder The encoder instance calling the callback.
* \param metadata The final populated STREAMINFO block.
* \param client_data The callee's client data set through
* FLAC__stream_encoder_set_client_data().
* FLAC__stream_encoder_init_*().
*/
typedef void (*FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the progress callback.
*
* A function pointer matching this signature may be passed to
* FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE().
* 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
* FLAC__file_encoder_set_total_samples_estimate().
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
* \param encoder The encoder instance calling the callback.
* \param bytes_written Bytes written so far.
* \param samples_written Samples written so far.
* \param frames_written Frames written so far.
* \param total_frames_estimate The estimate of the total number of
* frames to be written.
* \param client_data The callee's client data set through
* FLAC__stream_encoder_init_*().
*/
typedef void (*FLAC__StreamEncoderProgressCallback)(const FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
/***********************************************************************
*
@@ -691,9 +873,10 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__Stream
/** Set the metadata blocks to be emitted to the stream before encoding.
* A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
* array of pointers to metadata blocks. The array is non-const since
* the encoder may need to change the \a is_last flag inside them.
* Otherwise, the encoder will not modify or free the blocks. It is up
* to the caller to free the metadata blocks after encoding.
* the encoder may need to change the \a is_last flag inside them, and
* in some cases update seek point offsets. Otherwise, the encoder will
* not modify or free the blocks. It is up to the caller to free the
* metadata blocks after encoding.
*
* \note
* The encoder stores only the \a metadata pointer; the passed-in array
@@ -706,11 +889,34 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__Stream
*
* \note
* By default the encoder does not create a SEEKTABLE. If one is supplied
* in the \a metadata array it will be written verbatim. However by itself
* this is not very useful as the user will not know the stream offsets for
* the seekpoints ahead of time. You must use the seekable stream encoder
* to generate a legal seektable
* (see FLAC__seekable_stream_encoder_set_metadata())
* in the \a metadata array, but the client has specified that it does not
* support seeking, then the SEEKTABLE will be written verbatim. However
* by itself this is not very useful as the client will not know the stream
* offsets for the seekpoints ahead of time. In order to get a proper
* seektable the client must support seeking. See next note.
*
* \note
* SEEKTABLE blocks are handled specially. Since you will not know
* the values for the seek point stream offsets, you should pass in
* a SEEKTABLE 'template', that is, a SEEKTABLE object with the
* required sample numbers (or placeholder points), with \c 0 for the
* \a frame_samples and \a stream_offset fields for each point. If the
* client has specified that it supports seeking by providing a seek
* callback to FLAC__stream_encoder_init_stream() (or by using
* FLAC__stream_encoder_init_file() or FLAC__stream_encoder_init_FILE()),
* then while it is encoding the encoder will fill the stream offsets in
* for you and when encoding is finished, it will seek back and write the
* real values into the SEEKTABLE block in the stream. There are helper
* routines for manipulating seektable template blocks; see metadata.h:
* FLAC__metadata_object_seektable_template_*(). If the client does
* not support seeking, the SEEKTABLE will have inaccurate offsets which
* will slow down or remove the ability to seek in the FLAC stream.
*
* \note
* The encoder instance \b will modify the first \c SEEKTABLE block
* as it transforms the template to a valid seektable while encoding,
* but it is still up to the caller to free all metadata blocks after
* encoding.
*
* \note
* A VORBIS_COMMENT block may be supplied. The vendor string in it
@@ -731,68 +937,6 @@ FLAC_API FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__Stream
*/
FLAC_API FLAC__bool FLAC__stream_encoder_set_metadata(FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the write callback.
* The supplied function will be called by the encoder anytime there is raw
* encoded data ready to write. It may include metadata mixed with encoded
* audio frames and the data is not guaranteed to be aligned on frame or
* metadata block boundaries.
*
* The only duty of the callback is to write out the \a bytes worth of data
* in \a buffer to the current position in the output stream. The arguments
* \a samples and \a current_frame are purely informational. If \a samples
* is greater than \c 0, then \a current_frame will hold the current frame
* number that is being written; otherwise, the write callback is being called
* to write metadata.
*
* \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_API FLAC__bool FLAC__stream_encoder_set_write_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback value);
/** Set the metadata callback.
* The supplied function will be called once at the end of encoding with
* the populated STREAMINFO structure. This is so file encoders can seek
* back to the beginning of the file and write the STREAMINFO block with
* the correct statistics after encoding (like minimum/maximum frame size
* and total samples).
*
* \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_API FLAC__bool FLAC__stream_encoder_set_metadata_callback(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderMetadataCallback value);
/** 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_API FLAC__bool FLAC__stream_encoder_set_client_data(FLAC__StreamEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
@@ -1021,24 +1165,141 @@ FLAC_API unsigned FLAC__stream_encoder_get_rice_parameter_search_dist(const FLAC
FLAC_API FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate(const FLAC__StreamEncoder *encoder);
/** Initialize the encoder instance.
* Should be called after FLAC__stream_encoder_new() and
*
* This flavor of initialization sets up the encoder to encode to a stream.
* I/O is performed via callbacks to the client. For encoding to a plain file
* via filename or open \c FILE*, FLAC__stream_encoder_init_file() and
* FLAC__stream_encoder_init_FILE() provide a simpler interface.
*
* This function should be called after FLAC__stream_encoder_new() and
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
* or FLAC__stream_encoder_process_interleaved(). Will set and return
* the encoder state, which will be FLAC__STREAM_ENCODER_OK if
* or FLAC__stream_encoder_process_interleaved().
* initialization succeeded.
*
* The call to FLAC__stream_encoder_init() currently will also immediately
* The call to FLAC__stream_encoder_init_stream() 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.
* \param encoder An uninitialized encoder instance.
* \param write_callback See FLAC__StreamEncoderWriteCallback. This
* pointer must not be \c NULL.
* \param seek_callback See FLAC__StreamEncoderSeekCallback. This
* pointer may be \c NULL if seeking is not
* supported. The encoder uses seeking to go back
* and write some some stream statistics to the
* STREAMINFO block; this is recommended but not
* necessary to create a valid FLAC stream. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy seek callback that just
* returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param tell_callback See FLAC__StreamEncoderTellCallback. This
* pointer may be \c NULL if seeking is not
* supported. If \a seek_callback is \c NULL then
* this argument will be ignored. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy tell callback that just
* returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired. If the client provides a seek callback,
* this function is not necessary as the encoder
* will automatically seek back and update the
* STREAMINFO block. It may also be \c NULL if the
* client does not support seeking, since it will
* have no way of going back to update the
* STREAMINFO. However the client can still supply
* a callback if it would like to know the details
* from the STREAMINFO.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderState
* \c FLAC__STREAM_ENCODER_OK if initialization was successful; see
* FLAC__StreamEncoderState for the meanings of other return values.
* \retval FLAC__StreamEncoderInitStatus
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
*/
FLAC_API FLAC__StreamEncoderState FLAC__stream_encoder_init(FLAC__StreamEncoder *encoder);
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_stream(FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
/** Initialize the encoder instance.
*
* This flavor of initialization sets up the encoder to encode to a plain
* file. For non-stdio streams, you must use
* FLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
*
* This function should be called after FLAC__stream_encoder_new() and
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
* or FLAC__stream_encoder_process_interleaved().
* initialization succeeded.
*
* The call to FLAC__stream_encoder_init_stream() 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.
* \param file An open file. The file should have been opened
* with mode \c "w+b" and rewound. The file
* becomes owned by the encoder and should not be
* manipulated by the client while encoding.
* Unless \a file is \c stdout, it will be closed
* when FLAC__stream_encoder_finish() is called.
* Note however that a proper SEEKTABLE cannot be
* created when encoding to \c stdout since it is
* not seekable.
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code encoder != NULL \endcode
* \code file != NULL \endcode
* \retval FLAC__StreamEncoderInitStatus
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
*/
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_FILE(FLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
/** Initialize the encoder instance.
*
* This flavor of initialization sets up the encoder to encode to a plain
* file. If POSIX fopen() semantics are not sufficient (for example,
* with Unicode filenames on Windows), you must use
* FLAC__stream_encodeR_init_FILE(), or FLAC__stream_encoder_init_stream()
* and provide callbacks for the I/O.
*
* This function should be called after FLAC__stream_encoder_new() and
* FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process()
* or FLAC__stream_encoder_process_interleaved().
* initialization succeeded.
*
* The call to FLAC__stream_encoder_init_stream() 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.
* \param filename The name of the file to encode to. The file will
* be opened with fopen(). Use \c NULL to encode to
* \c stdout. Note however that a proper SEEKTABLE
* cannot be created when encoding to \c stdout since
* it is not seekable.
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderInitStatus
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
*/
FLAC_API FLAC__StreamEncoderInitStatus FLAC__stream_encoder_init_file(FLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder

2
include/Makefile.am
View File

@@ -19,4 +19,4 @@ if FLaC__HAS_OGG
OGGFLAC_DIRS = OggFLAC OggFLAC++
endif
SUBDIRS = FLAC FLAC++ $(OGGFLAC_DIRS) share
SUBDIRS = FLAC FLAC++ $(OGGFLAC_DIRS) share test_libs_common

336
include/OggFLAC++/decoder.h
View File

@@ -34,8 +34,6 @@
#include "export.h"
#include "OggFLAC/file_decoder.h"
#include "OggFLAC/seekable_stream_decoder.h"
#include "OggFLAC/stream_decoder.h"
// we only need this for the state abstraction really...
#include "FLAC++/decoder.h"
@@ -55,40 +53,57 @@
* \ingroup oggflacpp
*
* \brief
* This module describes the three decoder layers provided by libOggFLAC++.
* This module describes the decoder layers provided by libOggFLAC++.
*
* The libOggFLAC++ decoder classes are object wrappers around their
* counterparts in libOggFLAC. All three decoding layers available in
* counterparts in libOggFLAC. All decoding layers available in
* libOggFLAC are also provided here. The interface is very similar;
* make sure to read the \link oggflac_decoder libOggFLAC decoder module \endlink.
*
* The only real difference here is that instead of passing in C function
* pointers for callbacks, you inherit from the decoder class and provide
* implementations for the callbacks in the derived class; because of this
* there is no need for a 'client_data' property.
* There are only two significant differences here. First, instead of
* passing in C function pointers for callbacks, you inherit from the
* decoder class and provide implementations for the callbacks in your
* derived class; because of this there is no need for a 'client_data'
* property.
*
* Second, there are two stream decoder classes. OggFLAC::Decoder::Stream
* is used for the same cases that OggFLAC__stream_decoder_init_stream() is
* used, and OggFLAC::Decoder::File is used for the same cases that
* OggFLAC__stream_decoder_init_FILE() and OggFLAC__stream_decoder_init_file()
* are used.
*/
namespace OggFLAC {
namespace Decoder {
// ============================================================
//
// Equivalent: OggFLAC__StreamDecoder
//
// ============================================================
/** \defgroup oggflacpp_stream_decoder OggFLAC++/decoder.h: stream decoder class
* \ingroup oggflacpp_decoder
*
* \brief
* This class wraps the ::OggFLAC__StreamDecoder.
*
* See the \link oggflac_stream_decoder libOggFLAC stream decoder module \endlink.
* See the \link oggflac_stream_decoder libOggFLAC stream decoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::OggFLAC__StreamDecoder.
/** This class wraps the ::OggFLAC__StreamDecoder. If you are
* decoding from a file, OggFLAC::Decoder::File may be more
* convenient.
*
* The usage of this class is similar to OggFLAC__StreamDecoder,
* except instead of providing callbacks to
* OggFLAC__stream_decoder_init_stream(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call Stream::init(). The rest of
* the calls work the same as in the C layer.
*
* Only the read, write, and error callbacks are mandatory. The
* others are optional; this class provides default
* implementations that do nothing. In order for seeking to work
* you must overide seek_callback(), tell_callback(),
* length_callback(), and eof_callback().
*/
class OggFLACPP_API Stream {
public:
@@ -105,43 +120,76 @@ namespace OggFLAC {
Stream();
virtual ~Stream();
/** Call after construction to check the that the object was created
* successfully. If not, use get_state() to find out why not.
*
* \{
*/
bool is_valid() const;
inline operator bool() const { return is_valid(); }
/* \} */
bool set_serial_number(long value);
bool set_metadata_respond(::FLAC__MetadataType type);
bool set_metadata_respond_application(const FLAC__byte id[4]);
bool set_metadata_respond_all();
bool set_metadata_ignore(::FLAC__MetadataType type);
bool set_metadata_ignore_application(const FLAC__byte id[4]);
bool set_metadata_ignore_all();
bool set_serial_number(long value); ///< See OggFLAC__stream_decoder_set_serial_number()
bool set_md5_checking(bool value); ///< See OggFLAC__stream_decoder_set_md5_checking()
bool set_metadata_respond(::FLAC__MetadataType type); ///< See OggFLAC__stream_decoder_set_metadata_respond()
bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See OggFLAC__stream_decoder_set_metadata_respond_application()
bool set_metadata_respond_all(); ///< See OggFLAC__stream_decoder_set_metadata_respond_all()
bool set_metadata_ignore(::FLAC__MetadataType type); ///< See OggFLAC__stream_decoder_set_metadata_ignore()
bool set_metadata_ignore_application(const FLAC__byte id[4]); ///< See OggFLAC__stream_decoder_set_metadata_ignore_application()
bool set_metadata_ignore_all(); ///< See OggFLAC__stream_decoder_set_metadata_ignore_all()
State get_state() const;
FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const;
unsigned get_channels() const;
::FLAC__ChannelAssignment get_channel_assignment() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
State get_state() const; ///< See OggFLAC__stream_decoder_get_state()
FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const; ///< See OggFLAC__stream_decoder_get_FLAC_stream_decoder_state()
bool get_md5_checking() const; ///< See OggFLAC__stream_decoder_get_md5_checking()
FLAC__uint64 get_total_samples() const; ///< See OggFLAC__stream_decoder_get_total_samples()
unsigned get_channels() const; ///< See OggFLAC__stream_decoder_get_channels()
::FLAC__ChannelAssignment get_channel_assignment() const; ///< See OggFLAC__stream_decoder_get_channel_assignment()
unsigned get_bits_per_sample() const; ///< See OggFLAC__stream_decoder_get_bits_per_sample()
unsigned get_sample_rate() const; ///< See OggFLAC__stream_decoder_get_sample_rate()
unsigned get_blocksize() const; ///< See OggFLAC__stream_decoder_get_blocksize()
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See OggFLAC__stream_decoder_init_stream().
*/
State init();
::FLAC__StreamDecoderInitStatus init();
void finish();
void finish(); ///< See OggFLAC__stream_decoder_finish()
bool flush();
bool reset();
bool flush(); ///< See OggFLAC__stream_decoder_flush()
bool reset(); ///< See OggFLAC__stream_decoder_reset()
bool process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_stream();
bool process_single(); ///< See OggFLAC__stream_decoder_process_single()
bool process_until_end_of_metadata(); ///< See OggFLAC__stream_decoder_process_until_end_of_metadata()
bool process_until_end_of_stream(); ///< See OggFLAC__stream_decoder_process_until_end_of_stream()
bool skip_single_frame(); ///< See OggFLAC__stream_decoder_skip_single_frame()
bool seek_absolute(FLAC__uint64 sample); ///< See OggFLAC__stream_decoder_seek_absolute()
protected:
/// see FLAC__StreamDecoderReadCallback
virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
/// see FLAC__StreamDecoderSeekCallback
virtual ::FLAC__StreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
/// see FLAC__StreamDecoderTellCallback
virtual ::FLAC__StreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
/// see FLAC__StreamDecoderLengthCallback
virtual ::FLAC__StreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length);
/// see FLAC__StreamDecoderEofCallback
virtual bool eof_callback();
/// see FLAC__StreamDecoderWriteCallback
virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
/// see FLAC__StreamDecoderMetadataCallback
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
/// see FLAC__StreamDecoderErrorCallback
virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
@@ -149,12 +197,16 @@ namespace OggFLAC {
friend State;
#endif
::OggFLAC__StreamDecoder *decoder_;
private:
static ::FLAC__StreamDecoderReadStatus read_callback_(const ::OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::OggFLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::OggFLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::OggFLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
static ::FLAC__StreamDecoderReadStatus read_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__StreamDecoderSeekStatus seek_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__StreamDecoderTellStatus tell_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static ::FLAC__StreamDecoderLengthStatus length_callback_(const ::FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
static FLAC__bool eof_callback_(const ::FLAC__StreamDecoder *decoder, void *client_data);
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::FLAC__StreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::FLAC__StreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
private:
// Private and undefined so you can't use them:
Stream(const Stream &);
void operator=(const Stream &);
@@ -162,188 +214,56 @@ namespace OggFLAC {
/* \} */
// ============================================================
//
// Equivalent: OggFLAC__SeekableStreamDecoder
//
// ============================================================
/** \defgroup oggflacpp_seekable_stream_decoder OggFLAC++/decoder.h: seekable stream decoder class
* \ingroup oggflacpp_decoder
*
* \brief
* This class wraps the ::OggFLAC__SeekableStreamDecoder.
*
* See the \link oggflac_seekable_stream_decoder libOggFLAC seekable stream decoder module \endlink.
*
* \{
*/
/** This class wraps the ::OggFLAC__SeekableStreamDecoder.
*/
class OggFLACPP_API SeekableStream {
public:
class OggFLACPP_API State {
public:
inline State(::OggFLAC__SeekableStreamDecoderState state): state_(state) { }
inline operator ::OggFLAC__SeekableStreamDecoderState() const { return state_; }
inline const char *as_cstring() const { return ::OggFLAC__SeekableStreamDecoderStateString[state_]; }
inline const char *resolved_as_cstring(const SeekableStream &decoder) const { return ::OggFLAC__seekable_stream_decoder_get_resolved_state_string(decoder.decoder_); }
protected:
::OggFLAC__SeekableStreamDecoderState state_;
};
SeekableStream();
virtual ~SeekableStream();
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_serial_number(long value);
bool set_md5_checking(bool value);
bool set_metadata_respond(::FLAC__MetadataType type);
bool set_metadata_respond_application(const FLAC__byte id[4]);
bool set_metadata_respond_all();
bool set_metadata_ignore(::FLAC__MetadataType type);
bool set_metadata_ignore_application(const FLAC__byte id[4]);
bool set_metadata_ignore_all();
State get_state() const;
OggFLAC::Decoder::Stream::State get_stream_decoder_state() const;
FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const;
bool get_md5_checking() const;
unsigned get_channels() const;
::FLAC__ChannelAssignment get_channel_assignment() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
State init();
bool finish();
bool flush();
bool reset();
bool process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_stream();
bool seek_absolute(FLAC__uint64 sample);
protected:
virtual ::OggFLAC__SeekableStreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
virtual ::OggFLAC__SeekableStreamDecoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
virtual ::OggFLAC__SeekableStreamDecoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
virtual ::OggFLAC__SeekableStreamDecoderLengthStatus length_callback(FLAC__uint64 *stream_length) = 0;
virtual bool eof_callback() = 0;
virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::OggFLAC__SeekableStreamDecoder *decoder_;
private:
static ::OggFLAC__SeekableStreamDecoderReadStatus read_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::OggFLAC__SeekableStreamDecoderSeekStatus seek_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::OggFLAC__SeekableStreamDecoderTellStatus tell_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static ::OggFLAC__SeekableStreamDecoderLengthStatus length_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
static FLAC__bool eof_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::OggFLAC__SeekableStreamDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
// Private and undefined so you can't use them:
SeekableStream(const SeekableStream &);
void operator=(const SeekableStream &);
};
/* \} */
// ============================================================
//
// Equivalent: OggFLAC__FileDecoder
//
// ============================================================
/** \defgroup oggflacpp_file_decoder OggFLAC++/decoder.h: file decoder class
* \ingroup oggflacpp_decoder
*
* \brief
* This class wraps the ::OggFLAC__FileDecoder.
*
* See the \link oggflac_file_decoder libOggFLAC file decoder module \endlink.
* See the \link oggflac_file_decoder libOggFLAC file decoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::OggFLAC__FileDecoder.
/** This class wraps the ::OggFLAC__StreamDecoder. If you are
* not decoding from a file, you may need to use
* OggFLAC::Decoder::Stream.
*
* The usage of this class is similar to OggFLAC__StreamDecoder,
* except instead of providing callbacks to
* OggFLAC__stream_decoder_init_FILE() or
* OggFLAC__stream_decoder_init_file(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call File::init(). The rest of
* the calls work the same as in the C layer.
*
* Only the write, and error callbacks from OggFLAC::Decoder::Stream
* are mandatory. The others are optional; this class provides
* full working implementations for all other callbacks and
* supports seeking.
*/
class OggFLACPP_API File {
class OggFLACPP_API File: public Stream {
public:
class OggFLACPP_API State {
public:
inline State(::OggFLAC__FileDecoderState state): state_(state) { }
inline operator ::OggFLAC__FileDecoderState() const { return state_; }
inline const char *as_cstring() const { return ::OggFLAC__FileDecoderStateString[state_]; }
inline const char *resolved_as_cstring(const File &decoder) const { return ::OggFLAC__file_decoder_get_resolved_state_string(decoder.decoder_); }
protected:
::OggFLAC__FileDecoderState state_;
};
File();
virtual ~File();
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_serial_number(long value);
bool set_md5_checking(bool value);
bool set_filename(const char *value); //!< 'value' may not be \c NULL; use "-" for stdin
bool set_metadata_respond(::FLAC__MetadataType type);
bool set_metadata_respond_application(const FLAC__byte id[4]);
bool set_metadata_respond_all();
bool set_metadata_ignore(::FLAC__MetadataType type);
bool set_metadata_ignore_application(const FLAC__byte id[4]);
bool set_metadata_ignore_all();
State get_state() const;
OggFLAC::Decoder::SeekableStream::State get_seekable_stream_decoder_state() const;
OggFLAC::Decoder::Stream::State get_stream_decoder_state() const;
FLAC::Decoder::Stream::State get_FLAC_stream_decoder_state() const;
bool get_md5_checking() const;
unsigned get_channels() const;
::FLAC__ChannelAssignment get_channel_assignment() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
State init();
bool finish();
bool process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_file();
bool seek_absolute(FLAC__uint64 sample);
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See OggFLAC__stream_decoder_init_FILE() and
* OggFLAC__stream_decoder_init_file().
* \{
*/
::FLAC__StreamDecoderInitStatus init(FILE *file);
::FLAC__StreamDecoderInitStatus init(const char *filename);
::FLAC__StreamDecoderInitStatus init(const std::string &filename);
/* \} */
protected:
virtual ::FLAC__StreamDecoderWriteStatus write_callback(const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[]) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
virtual void error_callback(::FLAC__StreamDecoderErrorStatus status) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected decoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::OggFLAC__FileDecoder *decoder_;
// this is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
virtual ::FLAC__StreamDecoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
private:
static ::FLAC__StreamDecoderWriteStatus write_callback_(const ::OggFLAC__FileDecoder *decoder, const ::FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
static void metadata_callback_(const ::OggFLAC__FileDecoder *decoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static void error_callback_(const ::OggFLAC__FileDecoder *decoder, ::FLAC__StreamDecoderErrorStatus status, void *client_data);
// Private and undefined so you can't use them:
File(const File &);
void operator=(const File &);

387
include/OggFLAC++/encoder.h
View File

@@ -34,8 +34,6 @@
#include "export.h"
#include "OggFLAC/file_encoder.h"
#include "OggFLAC/seekable_stream_encoder.h"
#include "OggFLAC/stream_encoder.h"
#include "decoder.h"
// we only need these for the state abstractions really...
@@ -57,40 +55,58 @@
* \ingroup oggflacpp
*
* \brief
* This module describes the three encoder layers provided by libOggFLAC++.
* This module describes the encoder layers provided by libOggFLAC++.
*
* The libOggFLAC++ encoder classes are object wrappers around their
* counterparts in libOggFLAC. All three encoding layers available in
* counterparts in libOggFLAC. All decoding layers available in
* libOggFLAC are also provided here. The interface is very similar;
* make sure to read the \link oggflac_encoder libOggFLAC encoder module \endlink.
*
* The only real difference here is that instead of passing in C function
* pointers for callbacks, you inherit from the encoder class and provide
* implementations for the callbacks in the derived class; because of this
* there is no need for a 'client_data' property.
* There are only two significant differences here. First, instead of
* passing in C function pointers for callbacks, you inherit from the
* encoder class and provide implementations for the callbacks in your
* derived class; because of this there is no need for a 'client_data'
* property.
*
* Second, there are two stream encoder classes. OggFLAC::Encoder::Stream
* is used for the same cases that OggFLAC__stream_encoder_init_stream() is
* used, and OggFLAC::Encoder::File is used for the same cases that
* OggFLAC__stream_encoder_init_FILE() and OggFLAC__stream_encoder_init_file()
* are used.
*/
namespace OggFLAC {
namespace Encoder {
// ============================================================
//
// Equivalent: OggFLAC__StreamEncoder
//
// ============================================================
/** \defgroup oggflacpp_stream_encoder OggFLAC++/encoder.h: stream encoder class
* \ingroup oggflacpp_encoder
*
* \brief
* This class wraps the ::OggFLAC__StreamEncoder.
*
* See the \link oggflac_stream_encoder libOggFLAC stream encoder module \endlink.
* See the \link oggflac_stream_encoder libOggFLAC stream encoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::OggFLAC__StreamEncoder.
/** This class wraps the ::OggFLAC__StreamEncoder. If you are
* encoding to a file, OggFLAC::Encoder::File may be more
* convenient.
*
* The usage of this class is similar to OggFLAC__StreamEncoder,
* except instead of providing callbacks to
* OggFLAC__stream_encoder_init_stream(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call Stream::init(). The rest of
* the calls work the same as in the C layer.
*
* Only the write callback is mandatory. The others are
* optional; this class provides default implementations that do
* nothing. In order for some STREAMINFO and SEEKTABLE data to
* be written properly, you must overide read_callback(), seek_callback() and
* tell_callback(); see OggFLAC__stream_encoder_init_stream() as to
* why.
*/
class OggFLACPP_API Stream {
public:
@@ -107,71 +123,99 @@ namespace OggFLAC {
Stream();
virtual ~Stream();
/** Call after construction to check the that the object was created
* successfully. If not, use get_state() to find out why not.
*
* \{
*/
bool is_valid() const;
inline operator bool() const { return is_valid(); }
/* \} */
bool set_serial_number(long value);
bool set_verify(bool value);
bool set_streamable_subset(bool value);
bool set_do_mid_side_stereo(bool value);
bool set_loose_mid_side_stereo(bool value);
bool set_channels(unsigned value);
bool set_bits_per_sample(unsigned value);
bool set_sample_rate(unsigned value);
bool set_blocksize(unsigned value);
bool set_apodization(const char *specification);
bool set_max_lpc_order(unsigned value);
bool set_qlp_coeff_precision(unsigned value);
bool set_do_qlp_coeff_prec_search(bool value);
bool set_do_escape_coding(bool value);
bool set_do_exhaustive_model_search(bool value);
bool set_min_residual_partition_order(unsigned value);
bool set_max_residual_partition_order(unsigned value);
bool set_rice_parameter_search_dist(unsigned value);
bool set_total_samples_estimate(FLAC__uint64 value);
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
bool set_serial_number(long value); ///< See OggFLAC__stream_encoder_set_serial_number()
bool set_verify(bool value); ///< See OggFLAC__stream_encoder_set_verify()
bool set_streamable_subset(bool value); ///< See OggFLAC__stream_encoder_set_streamable_subset()
bool set_do_mid_side_stereo(bool value); ///< See OggFLAC__stream_encoder_set_do_mid_side_stereo()
bool set_loose_mid_side_stereo(bool value); ///< See OggFLAC__stream_encoder_set_loose_mid_side_stereo()
bool set_channels(unsigned value); ///< See OggFLAC__stream_encoder_set_channels()
bool set_bits_per_sample(unsigned value); ///< See OggFLAC__stream_encoder_set_bits_per_sample()
bool set_sample_rate(unsigned value); ///< See OggFLAC__stream_encoder_set_sample_rate()
bool set_blocksize(unsigned value); ///< See OggFLAC__stream_encoder_set_blocksize()
bool set_apodization(const char *specification); ///< See OggFLAC__stream_encoder_set_apodization()
bool set_max_lpc_order(unsigned value); ///< See OggFLAC__stream_encoder_set_max_lpc_order()
bool set_qlp_coeff_precision(unsigned value); ///< See OggFLAC__stream_encoder_set_qlp_coeff_precision()
bool set_do_qlp_coeff_prec_search(bool value); ///< See OggFLAC__stream_encoder_set_do_qlp_coeff_prec_search()
bool set_do_escape_coding(bool value); ///< See OggFLAC__stream_encoder_set_do_escape_coding()
bool set_do_exhaustive_model_search(bool value); ///< See OggFLAC__stream_encoder_set_do_exhaustive_model_search()
bool set_min_residual_partition_order(unsigned value); ///< See OggFLAC__stream_encoder_set_min_residual_partition_order()
bool set_max_residual_partition_order(unsigned value); ///< See OggFLAC__stream_encoder_set_max_residual_partition_order()
bool set_rice_parameter_search_dist(unsigned value); ///< See OggFLAC__stream_encoder_set_rice_parameter_search_dist()
bool set_total_samples_estimate(FLAC__uint64 value); ///< See OggFLAC__stream_encoder_set_total_samples_estimate()
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks); ///< See OggFLAC__stream_encoder_set_metadata()
bool set_metadata(FLAC::Metadata::Prototype **metadata, unsigned num_blocks); ///< See OggFLAC__stream_encoder_set_metadata()
State get_state() const;
FLAC::Encoder::Stream::State get_FLAC_stream_encoder_state() const;
FLAC::Decoder::Stream::State get_verify_decoder_state() const;
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
bool get_verify() const;
bool get_streamable_subset() const;
bool get_do_mid_side_stereo() const;
bool get_loose_mid_side_stereo() const;
unsigned get_channels() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
unsigned get_max_lpc_order() const;
unsigned get_qlp_coeff_precision() const;
bool get_do_qlp_coeff_prec_search() const;
bool get_do_escape_coding() const;
bool get_do_exhaustive_model_search() const;
unsigned get_min_residual_partition_order() const;
unsigned get_max_residual_partition_order() const;
unsigned get_rice_parameter_search_dist() const;
FLAC__uint64 get_total_samples_estimate() const;
State get_state() const; ///< See OggFLAC__stream_encoder_get_state()
FLAC::Encoder::Stream::State get_FLAC_stream_encoder_state() const; ///< See OggFLAC__stream_encoder_get_FLAC_stream_encoder_state()
FLAC::Decoder::Stream::State get_verify_decoder_state() const; ///< See OggFLAC__stream_encoder_get_verify_decoder_state()
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got); ///< See OggFLAC__stream_encoder_get_verify_decoder_error_stats()
bool get_verify() const; ///< See OggFLAC__stream_encoder_get_verify()
bool get_streamable_subset() const; ///< See OggFLAC__stream_encoder_get_streamable_subset()
bool get_do_mid_side_stereo() const; ///< See OggFLAC__stream_encoder_get_do_mid_side_stereo()
bool get_loose_mid_side_stereo() const; ///< See OggFLAC__stream_encoder_get_loose_mid_side_stereo()
unsigned get_channels() const; ///< See OggFLAC__stream_encoder_get_channels()
unsigned get_bits_per_sample() const; ///< See OggFLAC__stream_encoder_get_bits_per_sample()
unsigned get_sample_rate() const; ///< See OggFLAC__stream_encoder_get_sample_rate()
unsigned get_blocksize() const; ///< See OggFLAC__stream_encoder_get_blocksize()
unsigned get_max_lpc_order() const; ///< See OggFLAC__stream_encoder_get_max_lpc_order()
unsigned get_qlp_coeff_precision() const; ///< See OggFLAC__stream_encoder_get_qlp_coeff_precision()
bool get_do_qlp_coeff_prec_search() const; ///< See OggFLAC__stream_encoder_get_do_qlp_coeff_prec_search()
bool get_do_escape_coding() const; ///< See OggFLAC__stream_encoder_get_do_escape_coding()
bool get_do_exhaustive_model_search() const; ///< See OggFLAC__stream_encoder_get_do_exhaustive_model_search()
unsigned get_min_residual_partition_order() const; ///< See OggFLAC__stream_encoder_get_min_residual_partition_order()
unsigned get_max_residual_partition_order() const; ///< See OggFLAC__stream_encoder_get_max_residual_partition_order()
unsigned get_rice_parameter_search_dist() const; ///< See OggFLAC__stream_encoder_get_rice_parameter_search_dist()
FLAC__uint64 get_total_samples_estimate() const; ///< See OggFLAC__stream_encoder_get_total_samples_estimate()
State init();
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See OggFLAC__stream_encoder_init_stream().
*/
::FLAC__StreamEncoderInitStatus init();
void finish();
void finish(); ///< See OggFLAC__stream_encoder_finish()
bool process(const FLAC__int32 * const buffer[], unsigned samples);
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
bool process(const FLAC__int32 * const buffer[], unsigned samples); ///< See OggFLAC__stream_encoder_process()
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples); ///< See OggFLAC__stream_encoder_process_interleaved()
protected:
/// See OggFLAC__StreamEncoderReadCallback
virtual ::OggFLAC__StreamEncoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes);
/// See FLAC__StreamEncoderWriteCallback
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata) = 0;
/// See FLAC__StreamEncoderSeekCallback
virtual ::FLAC__StreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset);
/// See FLAC__StreamEncoderTellCallback
virtual ::FLAC__StreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset);
/// See FLAC__StreamEncoderTellCallback
virtual void metadata_callback(const ::FLAC__StreamMetadata *metadata);
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::OggFLAC__StreamEncoder *encoder_;
private:
static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
static void metadata_callback_(const ::OggFLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
static ::OggFLAC__StreamEncoderReadStatus read_callback_(const ::OggFLAC__StreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__StreamEncoderWriteStatus write_callback_(const ::FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
static ::FLAC__StreamEncoderSeekStatus seek_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__StreamEncoderTellStatus tell_callback_(const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static void metadata_callback_(const ::FLAC__StreamEncoder *encoder, const ::FLAC__StreamMetadata *metadata, void *client_data);
private:
// Private and undefined so you can't use them:
Stream(const Stream &);
void operator=(const Stream &);
@@ -179,202 +223,61 @@ namespace OggFLAC {
/* \} */
/** \defgroup oggflacpp_seekable_stream_encoder OggFLAC++/encoder.h: seekable stream encoder class
* \ingroup oggflacpp_encoder
*
* \brief
* This class wraps the ::OggFLAC__SeekableStreamEncoder.
*
* See the \link oggflac_seekable_stream_encoder libOggFLAC seekable stream encoder module \endlink.
*
* \{
*/
/** This class wraps the ::OggFLAC__SeekableStreamEncoder.
*/
class OggFLACPP_API SeekableStream {
public:
class OggFLACPP_API State {
public:
inline State(::OggFLAC__SeekableStreamEncoderState state): state_(state) { }
inline operator ::OggFLAC__SeekableStreamEncoderState() const { return state_; }
inline const char *as_cstring() const { return ::OggFLAC__SeekableStreamEncoderStateString[state_]; }
inline const char *resolved_as_cstring(const SeekableStream &encoder) const { return ::OggFLAC__seekable_stream_encoder_get_resolved_state_string(encoder.encoder_); }
protected:
::OggFLAC__SeekableStreamEncoderState state_;
};
SeekableStream();
virtual ~SeekableStream();
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_serial_number(long value);
bool set_verify(bool value);
bool set_streamable_subset(bool value);
bool set_do_mid_side_stereo(bool value);
bool set_loose_mid_side_stereo(bool value);
bool set_channels(unsigned value);
bool set_bits_per_sample(unsigned value);
bool set_sample_rate(unsigned value);
bool set_blocksize(unsigned value);
bool set_apodization(const char *specification);
bool set_max_lpc_order(unsigned value);
bool set_qlp_coeff_precision(unsigned value);
bool set_do_qlp_coeff_prec_search(bool value);
bool set_do_escape_coding(bool value);
bool set_do_exhaustive_model_search(bool value);
bool set_min_residual_partition_order(unsigned value);
bool set_max_residual_partition_order(unsigned value);
bool set_rice_parameter_search_dist(unsigned value);
bool set_total_samples_estimate(FLAC__uint64 value);
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
State get_state() const;
FLAC::Encoder::Stream::State get_FLAC_stream_encoder_state() const;
FLAC::Decoder::Stream::State get_verify_decoder_state() const;
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
bool get_verify() const;
bool get_streamable_subset() const;
bool get_do_mid_side_stereo() const;
bool get_loose_mid_side_stereo() const;
unsigned get_channels() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
unsigned get_max_lpc_order() const;
unsigned get_qlp_coeff_precision() const;
bool get_do_qlp_coeff_prec_search() const;
bool get_do_escape_coding() const;
bool get_do_exhaustive_model_search() const;
unsigned get_min_residual_partition_order() const;
unsigned get_max_residual_partition_order() const;
unsigned get_rice_parameter_search_dist() const;
FLAC__uint64 get_total_samples_estimate() const;
State init();
void finish();
bool process(const FLAC__int32 * const buffer[], unsigned samples);
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
protected:
virtual ::OggFLAC__SeekableStreamEncoderReadStatus read_callback(FLAC__byte buffer[], unsigned *bytes) = 0;
virtual ::FLAC__SeekableStreamEncoderSeekStatus seek_callback(FLAC__uint64 absolute_byte_offset) = 0;
virtual ::FLAC__SeekableStreamEncoderTellStatus tell_callback(FLAC__uint64 *absolute_byte_offset) = 0;
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame) = 0;
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::OggFLAC__SeekableStreamEncoder *encoder_;
private:
static ::OggFLAC__SeekableStreamEncoderReadStatus read_callback_(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
static ::FLAC__SeekableStreamEncoderSeekStatus seek_callback_(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
static ::FLAC__SeekableStreamEncoderTellStatus tell_callback_(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
static ::FLAC__StreamEncoderWriteStatus write_callback_(const OggFLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
// Private and undefined so you can't use them:
SeekableStream(const SeekableStream &);
void operator=(const SeekableStream &);
};
/* \} */
/** \defgroup oggflacpp_file_encoder OggFLAC++/encoder.h: file encoder class
* \ingroup oggflacpp_encoder
*
* \brief
* This class wraps the ::OggFLAC__FileEncoder.
*
* See the \link oggflac_file_encoder libOggFLAC file encoder module \endlink.
* See the \link oggflac_file_encoder libOggFLAC file encoder module \endlink
* for basic usage.
*
* \{
*/
/** This class wraps the ::OggFLAC__FileEncoder.
/** This class wraps the ::OggFLAC__StreamEncoder. If you are
* not encoding to a file, you may need to use
* OggFLAC::Encoder::Stream.
*
* The usage of this class is similar to OggFLAC__StreamEncoder,
* except instead of providing callbacks to
* OggFLAC__stream_encoder_init_FILE() or
* OggFLAC__stream_encoder_init_file(), you will inherit from this
* class and override the virtual callback functions with your
* own implementations, then call File::init(). The rest of
* the calls work the same as in the C layer.
*
* There are no mandatory callbacks; all the callbacks from
* OggFLAC::Encoder::Stream are implemented here fully and support
* full post-encode STREAMINFO and SEEKTABLE updating. There is
* only an optional progress callback which you may override to
* get periodic reports on the progress of the encode.
*/
class OggFLACPP_API File {
class OggFLACPP_API File: public Stream {
public:
class OggFLACPP_API State {
public:
inline State(::OggFLAC__FileEncoderState state): state_(state) { }
inline operator ::OggFLAC__FileEncoderState() const { return state_; }
inline const char *as_cstring() const { return ::OggFLAC__FileEncoderStateString[state_]; }
inline const char *resolved_as_cstring(const File &encoder) const { return ::OggFLAC__file_encoder_get_resolved_state_string(encoder.encoder_); }
protected:
::OggFLAC__FileEncoderState state_;
};
/** Initialize the instance; as with the C interface,
* init() should be called after construction and 'set'
* calls but before any of the 'process' calls.
*
* See OggFLAC__stream_encoder_init_FILE() and
* OggFLAC__stream_encoder_init_file().
* \{
*/
File();
virtual ~File();
/* \} */
bool is_valid() const;
inline operator bool() const { return is_valid(); }
bool set_serial_number(long value);
bool set_verify(bool value);
bool set_streamable_subset(bool value);
bool set_do_mid_side_stereo(bool value);
bool set_loose_mid_side_stereo(bool value);
bool set_channels(unsigned value);
bool set_bits_per_sample(unsigned value);
bool set_sample_rate(unsigned value);
bool set_blocksize(unsigned value);
bool set_apodization(const char *specification);
bool set_max_lpc_order(unsigned value);
bool set_qlp_coeff_precision(unsigned value);
bool set_do_qlp_coeff_prec_search(bool value);
bool set_do_escape_coding(bool value);
bool set_do_exhaustive_model_search(bool value);
bool set_min_residual_partition_order(unsigned value);
bool set_max_residual_partition_order(unsigned value);
bool set_rice_parameter_search_dist(unsigned value);
bool set_total_samples_estimate(FLAC__uint64 value);
bool set_metadata(::FLAC__StreamMetadata **metadata, unsigned num_blocks);
bool set_filename(const char *value);
State get_state() const;
SeekableStream::State get_seekable_stream_encoder_state() const;
FLAC::Encoder::Stream::State get_FLAC_stream_encoder_state() const;
FLAC::Decoder::Stream::State get_verify_decoder_state() const;
void get_verify_decoder_error_stats(FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
bool get_verify() const;
bool get_streamable_subset() const;
bool get_do_mid_side_stereo() const;
bool get_loose_mid_side_stereo() const;
unsigned get_channels() const;
unsigned get_bits_per_sample() const;
unsigned get_sample_rate() const;
unsigned get_blocksize() const;
unsigned get_max_lpc_order() const;
unsigned get_qlp_coeff_precision() const;
bool get_do_qlp_coeff_prec_search() const;
bool get_do_escape_coding() const;
bool get_do_exhaustive_model_search() const;
unsigned get_min_residual_partition_order() const;
unsigned get_max_residual_partition_order() const;
unsigned get_rice_parameter_search_dist() const;
FLAC__uint64 get_total_samples_estimate() const;
State init();
void finish();
bool process(const FLAC__int32 * const buffer[], unsigned samples);
bool process_interleaved(const FLAC__int32 buffer[], unsigned samples);
::FLAC__StreamEncoderInitStatus init(FILE *file);
::FLAC__StreamEncoderInitStatus init(const char *filename);
::FLAC__StreamEncoderInitStatus init(const std::string &filename);
protected:
/// See FLAC__StreamEncoderProgressCallback
virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
#if (defined _MSC_VER) || (defined __GNUG__ && (__GNUG__ < 2 || (__GNUG__ == 2 && __GNUC_MINOR__ < 96))) || (defined __SUNPRO_CC)
// lame hack: some MSVC/GCC versions can't see a protected encoder_ from nested State::resolved_as_cstring()
friend State;
#endif
::OggFLAC__FileEncoder *encoder_;
/// This is a dummy implementation to satisfy the pure virtual in Stream that is actually supplied internally by the C layer
virtual ::FLAC__StreamEncoderWriteStatus write_callback(const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame);
private:
static void progress_callback_(const ::OggFLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
static void progress_callback_(const ::FLAC__StreamEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
// Private and undefined so you can't use them:
File(const Stream &);

4
include/OggFLAC/Makefile.am
View File

@@ -36,9 +36,5 @@ oggflaccincludedir = $(includedir)/OggFLAC
oggflaccinclude_HEADERS = \
all.h \
export.h \
file_decoder.h \
file_encoder.h \
seekable_stream_decoder.h \
seekable_stream_encoder.h \
stream_decoder.h \
stream_encoder.h

4
include/OggFLAC/all.h
View File

@@ -38,10 +38,6 @@
#include "export.h"
#include "file_decoder.h"
#include "file_encoder.h"
#include "seekable_stream_decoder.h"
#include "seekable_stream_encoder.h"
#include "stream_decoder.h"
#include "stream_encoder.h"

621
include/OggFLAC/file_decoder.h
View File

@@ -1,621 +0,0 @@
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef OggFLAC__FILE_DECODER_H
#define OggFLAC__FILE_DECODER_H
#include "export.h"
#include "seekable_stream_decoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/OggFLAC/file_decoder.h
*
* \brief
* This module contains the functions which implement the file
* decoder.
*
* See the detailed documentation in the
* \link oggflac_file_decoder file decoder \endlink module.
*/
/** \defgroup oggflac_file_decoder OggFLAC/file_decoder.h: file decoder interface
* \ingroup oggflac_decoder
*
* \brief
* This module contains the functions which implement the file
* decoder.
*
* The interface here is nearly identical to FLAC's file decoder,
* including the callbacks, with the addition of
* OggFLAC__file_decoder_set_serial_number(). See the
* \link flac_file_decoder FLAC file decoder module \endlink
* for full documentation.
*
* \{
*/
/** 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,
/**< 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_SEEK_ERROR,
/**< An error occurred while seeking. */
OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying seekable stream decoder;
* check OggFLAC__file_decoder_get_seekable_stream_decoder_state().
*/
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_INVALID_CALLBACK,
/**< The decoder was initialized before setting all the required callbacks. */
OggFLAC__FILE_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} OggFLAC__FileDecoderState;
/** Maps an OggFLAC__FileDecoderState to a C string.
*
* Using an OggFLAC__FileDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern OggFLAC_API const char * const OggFLAC__FileDecoderStateString[];
/***********************************************************************
*
* class OggFLAC__FileDecoder : public OggFLAC__SeekableStreamDecoder
*
***********************************************************************/
struct OggFLAC__FileDecoderProtected;
struct OggFLAC__FileDecoderPrivate;
/** The opaque structure definition for the file decoder type. See the
* \link oggflac_file_decoder file decoder module \endlink for a detailed
* description.
*/
typedef struct {
struct OggFLAC__FileDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct OggFLAC__FileDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__FileDecoder;
/** Signature for the write callback.
* See OggFLAC__file_decoder_set_write_callback()
* and OggFLAC__SeekableStreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame.
* \param buffer An array of pointers to decoded channels of data.
* \param client_data The callee's client data set through
* OggFLAC__file_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__FileDecoderWriteCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See OggFLAC__file_decoder_set_metadata_callback()
* and OggFLAC__SeekableStreamDecoderMetadataCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param metadata The decoded metadata block.
* \param client_data The callee's client data set through
* OggFLAC__file_decoder_set_client_data().
*/
typedef void (*OggFLAC__FileDecoderMetadataCallback)(const OggFLAC__FileDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See OggFLAC__file_decoder_set_error_callback()
* and OggFLAC__SeekableStreamDecoderErrorCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param status The error encountered by the decoder.
* \param client_data The callee's client data set through
* OggFLAC__file_decoder_set_client_data().
*/
typedef void (*OggFLAC__FileDecoderErrorCallback)(const OggFLAC__FileDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new file decoder instance. The instance is created with
* default settings; see the individual OggFLAC__file_decoder_set_*()
* functions for each setting's default.
*
* \retval OggFLAC__FileDecoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
OggFLAC_API OggFLAC__FileDecoder *OggFLAC__file_decoder_new();
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
*
* \param decoder A pointer to an existing decoder.
* \assert
* \code decoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__file_decoder_delete(OggFLAC__FileDecoder *decoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** Set the "MD5 signature checking" flag.
* This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_set_md5_checking().
*
* \default \c false
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API 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.
* \param value The input file name, or "-" for \c stdin.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, or there was a memory
* allocation error, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_filename(OggFLAC__FileDecoder *decoder, const char *value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_write_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderWriteCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderMetadataCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_error_callback(OggFLAC__FileDecoder *decoder, OggFLAC__FileDecoderErrorCallback value);
/** 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 decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_client_data(OggFLAC__FileDecoder *decoder, void *value);
/** Set the serial number for the Ogg stream.
* The default behavior is to use the serial number of the first Ogg
* page. Setting a serial number here will explicitly specify which
* stream is to be decoded.
*
* \default \c use serial number of first page
* \param decoder A decoder instance to set.
* \param serial_number See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_serial_number(OggFLAC__FileDecoder *decoder, long serial_number);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond(OggFLAC__FileDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_respond_all(OggFLAC__FileDecoder *decoder);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore(OggFLAC__FileDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_application(OggFLAC__FileDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_set_metadata_ignore_all(OggFLAC__FileDecoder *decoder);
/** Get the current decoder state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__FileDecoderState
* The current decoder state.
*/
OggFLAC_API OggFLAC__FileDecoderState OggFLAC__file_decoder_get_state(const OggFLAC__FileDecoder *decoder);
/** Get the state of the underlying seekable stream decoder.
* Useful when the file decoder state is
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__FileDecoderState
* The seekable stream decoder state.
*/
OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__file_decoder_get_seekable_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
/** Get the state of the underlying 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.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__StreamDecoderState
* The stream decoder state.
*/
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__file_decoder_get_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
/** Get the state of the underlying FLAC 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
* and the stream decoder state is
* \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The FLAC stream decoder state.
*/
OggFLAC_API FLAC__StreamDecoderState OggFLAC__file_decoder_get_FLAC_stream_decoder_state(const OggFLAC__FileDecoder *decoder);
/** Get the current decoder state as a C string.
* This version automatically resolves
* \c OggFLAC__FILE_DECODER_SEEKABLE_STREAM_DECODER_ERROR
* by getting the seekable stream decoder's state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval const char *
* The decoder state as a C string. Do not modify the contents.
*/
OggFLAC_API const char *OggFLAC__file_decoder_get_resolved_state_string(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
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_get_md5_checking(const OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__file_decoder_get_channels(const OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__ChannelAssignment
* See above.
*/
OggFLAC_API FLAC__ChannelAssignment OggFLAC__file_decoder_get_channel_assignment(const OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__file_decoder_get_bits_per_sample(const OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__file_decoder_get_sample_rate(const OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__file_decoder_get_blocksize(const OggFLAC__FileDecoder *decoder);
/** Initialize the decoder instance.
* Should be called after OggFLAC__file_decoder_new() and
* OggFLAC__file_decoder_set_*() but before any of the
* OggFLAC__file_decoder_process_*() functions. Will set and return
* the decoder state, which will be OggFLAC__FILE_DECODER_OK if
* initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__FileDecoderState
* \c OggFLAC__FILE_DECODER_OK if initialization was successful; see
* OggFLAC__FileDecoderState for the meanings of other return values.
*/
OggFLAC_API OggFLAC__FileDecoderState OggFLAC__file_decoder_init(OggFLAC__FileDecoder *decoder);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
* settings to their defaults, and returns the decoder state to
* OggFLAC__FILE_DECODER_UNINITIALIZED.
*
* 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
* an OggFLAC__file_decoder_finish().
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if MD5 checking is on AND a STREAMINFO block was available
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
* signature does not match the one computed by the decoder; else
* \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_finish(OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_single(OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_until_end_of_metadata(OggFLAC__FileDecoder *decoder);
/** This is inherited from FLAC__FileDecoder; see
* FLAC__file_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_process_until_end_of_file(OggFLAC__FileDecoder *decoder);
/** This is inherited from OggFLAC__SeekableStreamDecoder; see
* OggFLAC__seekable_stream_decoder_seek_absolute().
*
* \param decoder A decoder instance.
* \param sample The target sample number to seek to.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false.
*/
OggFLAC_API FLAC__bool OggFLAC__file_decoder_seek_absolute(OggFLAC__FileDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

888
include/OggFLAC/file_encoder.h
View File

@@ -1,888 +0,0 @@
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef OggFLAC__FILE_ENCODER_H
#define OggFLAC__FILE_ENCODER_H
#include "export.h"
#include "seekable_stream_encoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/OggFLAC/file_encoder.h
*
* \brief
* This module contains the functions which implement the file
* encoder.
*
* See the detailed documentation in the
* \link oggflac_file_encoder file encoder \endlink module.
*/
/** \defgroup oggflac_file_encoder OggFLAC/file_encoder.h: file encoder interface
* \ingroup oggflac_encoder
*
* \brief
* This module contains the functions which implement the file
* encoder. Unlink the Ogg stream and seekable stream encoders, which
* derive from their FLAC counterparts, the Ogg file encoder is derived
* from the Ogg seekable stream encoder.
*
* The interface here is nearly identical to FLAC's file
* encoder, including the callbacks, with the addition of
* OggFLAC__file_encoder_set_serial_number(). See the
* \link flac_file_encoder FLAC file encoder module \endlink
* for full documentation.
*
* \{
*/
/** State values for a OggFLAC__FileEncoder
*
* The encoder's state can be obtained by calling OggFLAC__file_encoder_get_state().
*/
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_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_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
OggFLAC__FILE_ENCODER_ALREADY_INITIALIZED,
/**< OggFLAC__file_encoder_init() was called when the encoder was
* already initialized, usually because
* OggFLAC__file_encoder_finish() was not called.
*/
OggFLAC__FILE_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
} OggFLAC__FileEncoderState;
/** Maps a FLAC__FileEncoderState to a C string.
*
* Using a FLAC__FileEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern OggFLAC_API const char * const OggFLAC__FileEncoderStateString[];
/***********************************************************************
*
* class FLAC__FileEncoder
*
***********************************************************************/
struct OggFLAC__FileEncoderProtected;
struct OggFLAC__FileEncoderPrivate;
/** The opaque structure definition for the file encoder type.
* See the \link oggflac_file_encoder file encoder module \endlink
* for a detailed description.
*/
typedef struct {
struct OggFLAC__FileEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct OggFLAC__FileEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__FileEncoder;
/** Signature for the progress callback.
* See OggFLAC__file_encoder_set_progress_callback()
* and FLAC__FileEncoderProgressCallback for more info.
*
* \param encoder The encoder instance calling the callback.
* \param bytes_written Bytes written so far.
* \param samples_written Samples written so far.
* \param frames_written Frames written so far.
* \param total_frames_estimate The estimate of the total number of
* frames to be written.
* \param client_data The callee's client data set through
* OggFLAC__file_encoder_set_client_data().
*/
typedef void (*OggFLAC__FileEncoderProgressCallback)(const OggFLAC__FileEncoder *encoder, FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new file encoder instance. The instance is created with
* default settings; see the individual OggFLAC__file_encoder_set_*()
* functions for each setting's default.
*
* \retval OggFLAC__FileEncoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
OggFLAC_API OggFLAC__FileEncoder *OggFLAC__file_encoder_new();
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
*
* \param encoder A pointer to an existing encoder.
* \assert
* \code encoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__file_encoder_delete(OggFLAC__FileEncoder *encoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** Set the serial number for the FLAC stream.
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param serial_number See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_serial_number(OggFLAC__FileEncoder *encoder, long serial_number);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_verify().
*
* \default \c true
* \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.
*/
OggFLAC_API 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().
*
* \default \c true
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \warning
* Do not feed the encoder data that is wider than the value you
* set here or you will generate an invalid stream.
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_blocksize(OggFLAC__FileEncoder *encoder, unsigned value);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_set_apodization().
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param specification See above.
* \assert
* \code encoder != NULL \endcode
* \code specification != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_apodization(OggFLAC__FileEncoder *encoder, const char *specification);
/** This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_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.
*/
OggFLAC_API 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().
*
* \note
* In the current implementation, qlp_coeff_precision + bits_per_sample must
* be less than 32.
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \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.
*/
OggFLAC_API 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().
*
* \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
* the second metadata block of the stream. The encoder already supplies
* the STREAMINFO block automatically. If \a metadata does not contain a
* VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if
* \a metadata does contain a VORBIS_COMMENT block and it is not the
* first, this function will reorder \a metadata by moving the
* VORBIS_COMMENT block to the front; the relative ordering of the other
* blocks will remain as they were.
*
* \note The Ogg FLAC mapping limits the number of metadata blocks per
* stream to \c 65535. If \a num_blocks exceeds this the function will
* return \c false.
*
* \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, or if
* \a num_blocks > 65535, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_metadata(OggFLAC__FileEncoder *encoder, FLAC__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.
*
* \default \c NULL
* \param encoder A encoder instance to set.
* \param value The output file name.
* \assert
* \code encoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, or there was a memory
* allocation error, else \c true.
*/
OggFLAC_API 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.
*
* \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.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_progress_callback(OggFLAC__FileEncoder *encoder, OggFLAC__FileEncoderProgressCallback value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_set_client_data(OggFLAC__FileEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__FileEncoderState
* The current encoder state.
*/
OggFLAC_API OggFLAC__FileEncoderState OggFLAC__file_encoder_get_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying seekable stream encoder.
* Useful when the file encoder state is
* \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__SeekableStreamEncoderState
* The seekable stream encoder state.
*/
OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__file_encoder_get_seekable_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying FLAC 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_FLAC_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderState
* The seekable stream encoder state.
*/
OggFLAC_API FLAC__StreamEncoderState OggFLAC__file_encoder_get_FLAC_stream_encoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the state of the underlying stream encoder's verify decoder.
* 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_FLAC_STREAM_ENCODER_ERROR
* and the FLAC 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 stream encoder state.
*/
OggFLAC_API FLAC__StreamDecoderState OggFLAC__file_encoder_get_verify_decoder_state(const OggFLAC__FileEncoder *encoder);
/** Get the current encoder state as a C string.
* This version automatically resolves
* \c OggFLAC__FILE_ENCODER_SEEKABLE_STREAM_ENCODER_ERROR by getting the
* seekable stream encoder's state.
*
* \param encoder A encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval const char *
* The encoder state as a C string. Do not modify the contents.
*/
OggFLAC_API const char *OggFLAC__file_encoder_get_resolved_state_string(const OggFLAC__FileEncoder *encoder);
/** Get relevant values about the nature of a verify decoder error.
* Inherited from OggFLAC__seekable_stream_encoder_get_verify_decoder_error_stats().
* 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_FLAC_SEEKABLE_STREAM_ENCODER_ERROR
* and the FLAC seekable stream encoder state is
* \c FLAC__SEEKABLE_STREAM_ENCODER_STREAM_ENCODER_ERROR
* and the FLAC stream encoder state is
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \param encoder An encoder instance to query.
* \param absolute_sample The absolute sample number of the mismatch.
* \param frame_number The number of the frame in which the mismatch occurred.
* \param channel The channel in which the mismatch occurred.
* \param sample The number of the sample (relative to the frame) in
* which the mismatch occurred.
* \param expected The expected value for the sample in question.
* \param got The actual value returned by the decoder.
* \assert
* \code encoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__file_encoder_get_verify_decoder_error_stats(const OggFLAC__FileEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
/** Get the "verify" flag.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__seekable_stream_encoder_get_verify().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_set_verify().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_set_streamable_subset().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_get_do_mid_side_stereo().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_set_loose_mid_side_stereo().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See FLAC__file_encoder_set_channels().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_bits_per_sample().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_sample_rate().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_blocksize().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_max_lpc_order().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_qlp_coeff_precision().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_set_do_qlp_coeff_prec_search().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_set_do_escape_coding().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* See OggFLAC__file_encoder_set_do_exhaustive_model_search().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_min_residual_partition_order().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_max_residual_partition_order().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval unsigned
* See OggFLAC__file_encoder_set_rice_parameter_search_dist().
*/
OggFLAC_API 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().
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__uint64
* See OggFLAC__file_encoder_set_total_samples_estimate().
*/
OggFLAC_API FLAC__uint64 OggFLAC__file_encoder_get_total_samples_estimate(const OggFLAC__FileEncoder *encoder);
/** Initialize the encoder instance.
* Should be called after OggFLAC__file_encoder_new() and
* OggFLAC__file_encoder_set_*() but before OggFLAC__file_encoder_process()
* or OggFLAC__file_encoder_process_interleaved(). Will set and return
* the encoder state, which will be OggFLAC__FILE_ENCODER_OK if
* initialization succeeded.
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__FileEncoderState
* \c OggFLAC__FILE_ENCODER_OK if initialization was successful; see
* OggFLAC__FileEncoderState for the meanings of other return values.
*/
OggFLAC_API OggFLAC__FileEncoderState OggFLAC__file_encoder_init(OggFLAC__FileEncoder *encoder);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to
* OggFLAC__FILE_ENCODER_UNINITIALIZED.
*
* 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().
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__file_encoder_finish(OggFLAC__FileEncoder *encoder);
/** Submit data for encoding.
* This is inherited from OggFLAC__SeekableStreamEncoder; see
* OggFLAC__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.
* \param samples The number of samples in one channel.
* \assert
* \code encoder != NULL \endcode
* \code OggFLAC__file_encoder_get_state(encoder) == OggFLAC__FILE_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with OggFLAC__file_encoder_get_state() to see what
* went wrong.
*/
OggFLAC_API 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().
*
* \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__file_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__file_encoder_get_state(encoder) == OggFLAC__FILE_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with OggFLAC__file_encoder_get_state() to see what
* went wrong.
*/
OggFLAC_API FLAC__bool OggFLAC__file_encoder_process_interleaved(OggFLAC__FileEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

855
include/OggFLAC/seekable_stream_decoder.h
View File

@@ -1,855 +0,0 @@
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef OggFLAC__SEEKABLE_STREAM_DECODER_H
#define OggFLAC__SEEKABLE_STREAM_DECODER_H
#include "export.h"
#include "stream_decoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/OggFLAC/seekable_stream_decoder.h
*
* \brief
* This module contains the functions which implement the seekable stream
* decoder.
*
* See the detailed documentation in the
* \link oggflac_seekable_stream_decoder seekable stream decoder \endlink module.
*/
/** \defgroup oggflac_seekable_stream_decoder OggFLAC/seekable_stream_decoder.h: seekable stream decoder interface
* \ingroup oggflac_decoder
*
* \brief
* This module contains the functions which implement the seekable stream
* decoder.
*
* The interface here is nearly identical to FLAC's seekable stream decoder,
* including the callbacks, with the addition of
* OggFLAC__seekable_stream_decoder_set_serial_number(). See the
* \link flac_seekable_stream_decoder FLAC seekable stream decoder module \endlink
* for full documentation.
*
* \{
*/
/** 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,
/**< 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,
/**< Memory allocation failed. */
OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR,
/**< An error occurred in the underlying stream decoder;
* check OggFLAC__seekable_stream_decoder_get_stream_decoder_state().
*/
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_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,
/**< The decoder was initialized before setting all the required callbacks. */
OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
} OggFLAC__SeekableStreamDecoderState;
/** Maps an OggFLAC__SeekableStreamDecoderState to a C string.
*
* Using an OggFLAC__SeekableStreamDecoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern OggFLAC_API 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 OggFLAC_API 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 OggFLAC_API 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 OggFLAC_API 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 OggFLAC_API const char * const OggFLAC__SeekableStreamDecoderLengthStatusString[];
/***********************************************************************
*
* class OggFLAC__SeekableStreamDecoder : public FLAC__StreamDecoder
*
***********************************************************************/
struct OggFLAC__SeekableStreamDecoderProtected;
struct OggFLAC__SeekableStreamDecoderPrivate;
/** The opaque structure definition for the seekable stream decoder type.
* See the
* \link oggflac_seekable_stream_decoder seekable stream decoder module \endlink
* for a detailed description.
*/
typedef struct {
struct OggFLAC__SeekableStreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct OggFLAC__SeekableStreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__SeekableStreamDecoder;
/** Signature for the read callback.
* See OggFLAC__seekable_stream_decoder_set_read_callback()
* and OggFLAC__StreamDecoderReadCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param buffer A pointer to a location for the callee to store
* data to be decoded.
* \param bytes A pointer to the size of the buffer.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderReadStatus
* The callee's return status.
*/
typedef OggFLAC__SeekableStreamDecoderReadStatus (*OggFLAC__SeekableStreamDecoderReadCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the seek callback.
* See OggFLAC__seekable_stream_decoder_set_seek_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param absolute_byte_offset The offset from the beginning of the stream
* to seek to.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderSeekStatus
* The callee's return status.
*/
typedef OggFLAC__SeekableStreamDecoderSeekStatus (*OggFLAC__SeekableStreamDecoderSeekCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
* See OggFLAC__seekable_stream_decoder_set_tell_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param absolute_byte_offset A pointer to storage for the current offset
* from the beginning of the stream.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderTellStatus
* The callee's return status.
*/
typedef OggFLAC__SeekableStreamDecoderTellStatus (*OggFLAC__SeekableStreamDecoderTellCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the length callback.
* See OggFLAC__seekable_stream_decoder_set_length_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param stream_length A pointer to storage for the length of the stream
* in bytes.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__SeekableStreamDecoderLengthStatus
* The callee's return status.
*/
typedef OggFLAC__SeekableStreamDecoderLengthStatus (*OggFLAC__SeekableStreamDecoderLengthCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data);
/** Signature for the EOF callback.
* See OggFLAC__seekable_stream_decoder_set_eof_callback() for more info.
*
* \param decoder The decoder instance calling the callback.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__bool
* \c true if the currently at the end of the stream, else \c false.
*/
typedef FLAC__bool (*OggFLAC__SeekableStreamDecoderEofCallback)(const OggFLAC__SeekableStreamDecoder *decoder, void *client_data);
/** Signature for the write callback.
* See OggFLAC__seekable_stream_decoder_set_write_callback()
* and OggFLAC__StreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame.
* \param buffer An array of pointers to decoded channels of data.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__SeekableStreamDecoderWriteCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See OggFLAC__seekable_stream_decoder_set_metadata_callback()
* and OggFLAC__StreamDecoderMetadataCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param metadata The decoded metadata block.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
*/
typedef void (*OggFLAC__SeekableStreamDecoderMetadataCallback)(const OggFLAC__SeekableStreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See OggFLAC__seekable_stream_decoder_set_error_callback()
* and OggFLAC__StreamDecoderErrorCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param status The error encountered by the decoder.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_decoder_set_client_data().
*/
typedef void (*OggFLAC__SeekableStreamDecoderErrorCallback)(const OggFLAC__SeekableStreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new seekable stream decoder instance. The instance is created
* with default settings; see the individual
* OggFLAC__seekable_stream_decoder_set_*() functions for each setting's
* default.
*
* \retval OggFLAC__SeekableStreamDecoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
OggFLAC_API OggFLAC__SeekableStreamDecoder *OggFLAC__seekable_stream_decoder_new();
/** Free a decoder instance. Deletes the object pointed to by \a decoder.
*
* \param decoder A pointer to an existing decoder.
* \assert
* \code decoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__seekable_stream_decoder_delete(OggFLAC__SeekableStreamDecoder *decoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** 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.
* \param value Flag value (see above).
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_md5_checking(OggFLAC__SeekableStreamDecoder *decoder, FLAC__bool value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_read_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderReadCallback value);
/** Set the seek callback.
* 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_seek_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderSeekCallback value);
/** Set the tell callback.
* 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_tell_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderTellCallback value);
/** Set the length callback.
* 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_length_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderLengthCallback value);
/** Set the eof callback.
* 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_eof_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderEofCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_write_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderWriteCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderMetadataCallback value);
/** Set the 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.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_error_callback(OggFLAC__SeekableStreamDecoder *decoder, OggFLAC__SeekableStreamDecoderErrorCallback value);
/** 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 decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_client_data(OggFLAC__SeekableStreamDecoder *decoder, void *value);
/** Set the serial number for the Ogg stream.
* The default behavior is to use the serial number of the first Ogg
* page. Setting a serial number here will explicitly specify which
* stream is to be decoded.
*
* \default \c use serial number of first page
* \param decoder A decoder instance to set.
* \param serial_number See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_serial_number(OggFLAC__SeekableStreamDecoder *decoder, long serial_number);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond(OggFLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_respond_all(OggFLAC__SeekableStreamDecoder *decoder);
/** 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.
* \param decoder A decoder instance to set.
* \param type See above.
* \assert
* \code decoder != NULL \endcode
* \a type is valid
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore(OggFLAC__SeekableStreamDecoder *decoder, FLAC__MetadataType type);
/** 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.
* \param decoder A decoder instance to set.
* \param id See above.
* \assert
* \code decoder != NULL \endcode
* \code id != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_application(OggFLAC__SeekableStreamDecoder *decoder, const FLAC__byte id[4]);
/** 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.
* \param decoder A decoder instance to set.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_set_metadata_ignore_all(OggFLAC__SeekableStreamDecoder *decoder);
/** Get the current decoder state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__SeekableStreamDecoderState
* The current decoder state.
*/
OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_get_state(const OggFLAC__SeekableStreamDecoder *decoder);
/** Get the state of the underlying stream decoder.
* Useful when the seekable stream decoder state is
* \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__StreamDecoderState
* The stream decoder state.
*/
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
/** Get the state of the underlying stream decoder's FLAC stream decoder.
* Useful when the seekable stream decoder state is
* \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR and the
* stream decoder state is \c OggFLAC__STREAM_DECODER_FLAC_STREAM_DECODER_ERROR
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderState
* The FLAC stream decoder state.
*/
OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_decoder_get_FLAC_stream_decoder_state(const OggFLAC__SeekableStreamDecoder *decoder);
/** Get the current decoder state as a C string.
* This version automatically resolves
* \c OggFLAC__SEEKABLE_STREAM_DECODER_STREAM_DECODER_ERROR
* by getting the stream decoder's state.
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval const char *
* The decoder state as a C string. Do not modify the contents.
*/
OggFLAC_API const char *OggFLAC__seekable_stream_decoder_get_resolved_state_string(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
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_get_md5_checking(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channels().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_channels(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_channel_assignment().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__ChannelAssignment
* See above.
*/
OggFLAC_API FLAC__ChannelAssignment OggFLAC__seekable_stream_decoder_get_channel_assignment(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_bits_per_sample().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_bits_per_sample(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_sample_rate().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_sample_rate(const OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_get_blocksize().
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_decoder_get_blocksize(const OggFLAC__SeekableStreamDecoder *decoder);
/** Initialize the decoder instance.
* Should be called after OggFLAC__seekable_stream_decoder_new() and
* OggFLAC__seekable_stream_decoder_set_*() but before any of the
* OggFLAC__seekable_stream_decoder_process_*() functions. Will set and return
* the decoder state, which will be OggFLAC__SEEKABLE_STREAM_DECODER_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__SeekableStreamDecoderState
* \c OggFLAC__SEEKABLE_STREAM_DECODER_OK if initialization was
* successful; see OggFLAC__SeekableStreamDecoderState for the meanings
* of other return values.
*/
OggFLAC_API OggFLAC__SeekableStreamDecoderState OggFLAC__seekable_stream_decoder_init(OggFLAC__SeekableStreamDecoder *decoder);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
* settings to their defaults, and returns the decoder state to
* OggFLAC__SEEKABLE_STREAM_DECODER_UNINITIALIZED.
*
* In the event of a prematurely-terminated decode, it is not strictly
* necessary to call this immediately before
* OggFLAC__seekable_stream_decoder_delete() but it is good practice to match
* every OggFLAC__seekable_stream_decoder_init() with a
* OggFLAC__seekable_stream_decoder_finish().
*
* \param decoder An uninitialized decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if MD5 checking is on AND a STREAMINFO block was available
* AND the MD5 signature in the STREAMINFO block was non-zero AND the
* signature does not match the one computed by the decoder; else
* \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_finish(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_flush().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* or stream decoder error occurs.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_flush(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_reset().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* or stream decoder error occurs.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_reset(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_single().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_single(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_metadata().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_metadata(OggFLAC__SeekableStreamDecoder *decoder);
/** This is inherited from FLAC__SeekableStreamDecoder; see
* FLAC__seekable_stream_decoder_process_until_end_of_stream().
*
* \param decoder A decoder instance.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_process_until_end_of_stream(OggFLAC__SeekableStreamDecoder *decoder);
/** 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.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_decoder_seek_absolute(OggFLAC__SeekableStreamDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

949
include/OggFLAC/seekable_stream_encoder.h
View File

@@ -1,949 +0,0 @@
/* libOggFLAC - Free Lossless Audio Codec + Ogg library
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* - Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* - Neither the name of the Xiph.org Foundation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef OggFLAC__SEEKABLE_STREAM_ENCODER_H
#define OggFLAC__SEEKABLE_STREAM_ENCODER_H
#include "export.h"
#include "FLAC/stream_encoder.h"
#include "FLAC/seekable_stream_encoder.h"
#ifdef __cplusplus
extern "C" {
#endif
/** \file include/OggFLAC/seekable_stream_encoder.h
*
* \brief
* This module contains the functions which implement the seekable
* stream encoder.
*
* See the detailed documentation in the
* \link oggflac_seekable_stream_encoder seekable stream encoder \endlink module.
*/
/** \defgroup oggflac_seekable_stream_encoder OggFLAC/seekable_stream_encoder.h: seekable stream encoder interface
* \ingroup oggflac_encoder
*
* \brief
* This module contains the functions which implement the seekable
* stream encoder. The Ogg seekable stream encoder is derived
* from the FLAC seekable stream encoder.
*
* The interface here is nearly identical to FLAC's seekable stream
* encoder, including the callbacks, with the addition of a new required
* read callback (needed when writing back STREAMINFO after encoding) and
* OggFLAC__seekable_stream_encoder_set_serial_number(). See the
* \link flac_seekable_stream_encoder FLAC seekable stream encoder module \endlink
* for full documentation.
*
* \{
*/
/** State values for an OggFLAC__SeekableStreamEncoder
*
* The encoder's state can be obtained by calling OggFLAC__stream_encoder_get_state().
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
OggFLAC__SEEKABLE_STREAM_ENCODER_OGG_ERROR,
/**< An error occurred in the underlying Ogg layer. */
OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR,
/**< An error occurred in the underlying FLAC stream encoder;
* check OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state().
*/
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_TELL_ERROR,
/**< The tell 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 an OggFLAC__StreamEncoderState to a C string.
*
* Using an OggFLAC__StreamEncoderState as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern OggFLAC_API const char * const OggFLAC__SeekableStreamEncoderStateString[];
/** Return values for the OggFLAC__SeekableStreamEncoder read callback.
*/
typedef enum {
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_CONTINUE,
/**< The read was OK and decoding can continue. */
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
/**< The read was attempted at the end of the stream. */
OggFLAC__SEEKABLE_STREAM_ENCODER_READ_STATUS_ABORT
/**< An unrecoverable error occurred. */
} OggFLAC__SeekableStreamEncoderReadStatus;
/** Maps a OggFLAC__SeekableStreamEncoderReadStatus to a C string.
*
* Using a OggFLAC__SeekableStreamEncoderReadStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern OggFLAC_API const char * const OggFLAC__SeekableStreamEncoderReadStatusString[];
/***********************************************************************
*
* class OggFLAC__StreamEncoder
*
***********************************************************************/
struct OggFLAC__SeekableStreamEncoderProtected;
struct OggFLAC__SeekableStreamEncoderPrivate;
/** The opaque structure definition for the seekable stream encoder type.
* See the \link oggflac_seekable_stream_encoder seekable stream encoder module \endlink
* for a detailed description.
*/
typedef struct {
struct OggFLAC__SeekableStreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct OggFLAC__SeekableStreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__SeekableStreamEncoder;
/** Signature for the read callback.
* See OggFLAC__seekable_stream_encoder_set_read_callback() for more info.
*
* \param encoder The encoder instance calling the callback.
* \param buffer A pointer to a location for the callee to store
* data to be encoded.
* \param bytes A pointer to the size of the buffer. On entry
* to the callback, it contains the maximum number
* of bytes that may be stored in \a buffer. The
* callee must set it to the actual number of bytes
* stored (0 in case of error or end-of-stream) before
* returning.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_encoder_set_client_data().
* \retval OggFLAC__SeekableStreamEncoderReadStatus
* The callee's return status.
*/
typedef OggFLAC__SeekableStreamEncoderReadStatus (*OggFLAC__SeekableStreamEncoderReadCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the seek callback.
* See OggFLAC__seekable_stream_encoder_set_seek_callback()
* and FLAC__SeekableStreamEncoderSeekCallback for more info.
*
* \param encoder The encoder instance calling the callback.
* \param absolute_byte_offset The offset from the beginning of the stream
* to seek to.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_encoder_set_client_data().
* \retval FLAC__SeekableStreamEncoderSeekStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamEncoderSeekStatus (*OggFLAC__SeekableStreamEncoderSeekCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 absolute_byte_offset, void *client_data);
/** Signature for the tell callback.
* See OggFLAC__seekable_stream_encoder_set_tell_callback()
* and FLAC__SeekableStreamEncoderTellCallback for more info.
*
* \param encoder The encoder instance calling the callback.
* \param absolute_byte_offset The address at which to store the current
* position of the output.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_encoder_set_client_data().
* \retval FLAC__SeekableStreamEncoderTellStatus
* The callee's return status.
*/
typedef FLAC__SeekableStreamEncoderTellStatus (*OggFLAC__SeekableStreamEncoderTellCallback)(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_byte_offset, void *client_data);
/** Signature for the write callback.
* See OggFLAC__seekable_stream_encoder_set_write_callback()
* and FLAC__SeekableStreamEncoderWriteCallback for more info.
*
* \param encoder The encoder instance calling the callback.
* \param buffer An array of encoded data of length \a bytes.
* \param bytes The byte length of \a buffer.
* \param samples The number of samples encoded by \a buffer.
* \c 0 has a special meaning; see
* OggFLAC__seekable_stream_encoder_set_write_callback().
* \param current_frame The number of current frame being encoded.
* \param client_data The callee's client data set through
* OggFLAC__seekable_stream_encoder_set_client_data().
* \retval FLAC__StreamEncoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__SeekableStreamEncoderWriteCallback)(const OggFLAC__SeekableStreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
/***********************************************************************
*
* Class constructor/destructor
*
***********************************************************************/
/** Create a new seekable stream encoder instance. The instance is created with
* default settings; see the individual OggFLAC__seekable_stream_encoder_set_*()
* functions for each setting's default.
*
* \retval OggFLAC__SeekableStreamEncoder*
* \c NULL if there was an error allocating memory, else the new instance.
*/
OggFLAC_API OggFLAC__SeekableStreamEncoder *OggFLAC__seekable_stream_encoder_new();
/** Free an encoder instance. Deletes the object pointed to by \a encoder.
*
* \param encoder A pointer to an existing encoder.
* \assert
* \code encoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__seekable_stream_encoder_delete(OggFLAC__SeekableStreamEncoder *encoder);
/***********************************************************************
*
* Public class method prototypes
*
***********************************************************************/
/** Set the serial number for the FLAC stream.
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param serial_number See above.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_serial_number(OggFLAC__SeekableStreamEncoder *encoder, long serial_number);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_verify(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_streamable_subset(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_loose_mid_side_stereo(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_channels(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_bits_per_sample(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_sample_rate(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_blocksize(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_apodization()
*
* \default \c 0
* \param encoder An encoder instance to set.
* \param specification See above.
* \assert
* \code encoder != NULL \endcode
* \code specification != NULL \endcode
* \retval FLAC__bool
* \c false if the encoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_apodization(OggFLAC__SeekableStreamEncoder *encoder, const char *specification);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_max_lpc_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_qlp_coeff_precision(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_qlp_coeff_prec_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_escape_coding(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_do_exhaustive_model_search(OggFLAC__SeekableStreamEncoder *encoder, FLAC__bool value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_min_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_max_residual_partition_order(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_rice_parameter_search_dist(OggFLAC__SeekableStreamEncoder *encoder, unsigned value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_total_samples_estimate(OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 value);
/** This is inherited from FLAC__StreamEncoder; see FLAC__stream_encoder_set_metadata()
*
* \note The Ogg FLAC mapping requires that the VORBIS_COMMENT block be
* the second metadata block of the stream. The encoder already supplies
* the STREAMINFO block automatically. If \a metadata does not contain a
* VORBIS_COMMENT block, the encoder will supply that too. Otherwise, if
* \a metadata does contain a VORBIS_COMMENT block and it is not the
* first, this function will reorder \a metadata by moving the
* VORBIS_COMMENT block to the front; the relative ordering of the other
* blocks will remain as they were.
*
* \note The Ogg FLAC mapping limits the number of metadata blocks per
* stream to \c 65535. If \a num_blocks exceeds this the function will
* return \c false.
*
* \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, or if
* \a num_blocks > 65535, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_metadata(OggFLAC__SeekableStreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the read callback.
* The supplied function will be called when the encoder needs to read back
* encoded data. This happens during the metadata callback, when the encoder
* has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
* while encoding. 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__SeekableStreamEncoderReadStatus.
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param encoder A 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_read_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderReadCallback value);
/** Set the seek callback.
* The supplied function will be called when the encoder needs to seek
* the output stream. The encoder will pass the absolute byte offset
* to seek to, 0 meaning the beginning of the stream.
*
* \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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_seek_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderSeekCallback value);
/** Set the tell callback.
* The supplied function will be called when the encoder needs to know
* the current position of the output stream.
*
* \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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_tell_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderTellCallback value);
/** Set the write callback.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_write_callback().
*
* \note
* Unlike the FLAC seekable stream encoder write callback, the Ogg
* seekable stream encoder write callback will be called twice when
* writing audio frames; once for the page header, and once for the page
* body. When writing the page header, the \a samples argument to the
* write callback will be \c 0.
*
* \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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_write_callback(OggFLAC__SeekableStreamEncoder *encoder, OggFLAC__SeekableStreamEncoderWriteCallback value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_set_client_data(OggFLAC__SeekableStreamEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval OggFLAC__SeekableStreamEncoderState
* The current encoder state.
*/
OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_get_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying FLAC stream encoder.
* Useful when the seekable stream encoder state is
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR.
*
* \param encoder An encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderState
* The FLAC stream encoder state.
*/
OggFLAC_API FLAC__StreamEncoderState OggFLAC__seekable_stream_encoder_get_FLAC_stream_encoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the state of the underlying FLAC encoder's verify decoder.
* Useful when the seekable stream encoder state is
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
* and the FLAC 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.
*/
OggFLAC_API FLAC__StreamDecoderState OggFLAC__seekable_stream_encoder_get_verify_decoder_state(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get the current encoder state as a C string.
* This version automatically resolves
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
* by getting the FLAC stream encoder's resolved state.
*
* \param encoder A encoder instance to query.
* \assert
* \code encoder != NULL \endcode
* \retval const char *
* The encoder state as a C string. Do not modify the contents.
*/
OggFLAC_API const char *OggFLAC__seekable_stream_encoder_get_resolved_state_string(const OggFLAC__SeekableStreamEncoder *encoder);
/** Get relevant values about the nature of a verify decoder error.
* Inherited from FLAC__stream_encoder_get_verify_decoder_error_stats().
* Useful when the seekable stream encoder state is
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_FLAC_STREAM_ENCODER_ERROR
* and the FLAC stream encoder state is
* \c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR.
*
* \param encoder An encoder instance to query.
* \param absolute_sample The absolute sample number of the mismatch.
* \param frame_number The number of the frame in which the mismatch occurred.
* \param channel The channel in which the mismatch occurred.
* \param sample The number of the sample (relative to the frame) in
* which the mismatch occurred.
* \param expected The expected value for the sample in question.
* \param got The actual value returned by the decoder.
* \assert
* \code encoder != NULL \endcode
* \code absolute_sample != NULL \endcode
* \code frame_number != NULL \endcode
* \code channel != NULL \endcode
* \code sample != NULL \endcode
* \code expected != NULL \endcode
*/
OggFLAC_API void OggFLAC__seekable_stream_encoder_get_verify_decoder_error_stats(const OggFLAC__SeekableStreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got);
/** 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__seekable_stream_encoder_set_verify().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_verify(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_streamable_subset().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_streamable_subset(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_get_do_mid_side_stereo().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_loose_mid_side_stereo().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_loose_mid_side_stereo(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_channels().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_channels(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_bits_per_sample().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_bits_per_sample(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_sample_rate().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_sample_rate(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_blocksize().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_blocksize(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_max_lpc_order().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_max_lpc_order(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_qlp_coeff_precision().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_qlp_coeff_precision(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_do_qlp_coeff_prec_search().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_qlp_coeff_prec_search(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_do_escape_coding().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_escape_coding(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_do_exhaustive_model_search().
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_get_do_exhaustive_model_search(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_min_residual_partition_order().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_min_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_max_residual_partition_order().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_max_residual_partition_order(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_set_rice_parameter_search_dist().
*/
OggFLAC_API unsigned OggFLAC__seekable_stream_encoder_get_rice_parameter_search_dist(const OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_get_total_samples_estimate().
*/
OggFLAC_API FLAC__uint64 OggFLAC__seekable_stream_encoder_get_total_samples_estimate(const OggFLAC__SeekableStreamEncoder *encoder);
/** Initialize the encoder instance.
* Should be called after OggFLAC__seekable_stream_encoder_new() and
* OggFLAC__seekable_stream_encoder_set_*() but before OggFLAC__seekable_stream_encoder_process()
* or OggFLAC__seekable_stream_encoder_process_interleaved(). Will set and return
* the encoder state, which will be OggFLAC__SEEKABLE_STREAM_ENCODER_OK if
* initialization succeeded.
*
* The call to OggFLAC__seekable_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__SeekableStreamEncoderState
* \c OggFLAC__SEEKABLE_STREAM_ENCODER_OK if initialization was successful; see
* OggFLAC__SeekableStreamEncoderState for the meanings of other return values.
*/
OggFLAC_API OggFLAC__SeekableStreamEncoderState OggFLAC__seekable_stream_encoder_init(OggFLAC__SeekableStreamEncoder *encoder);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to
* OggFLAC__SEEKABLE_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__seekable_stream_encoder_delete()
* but it is good practice to match every OggFLAC__seekable_stream_encoder_init()
* with an OggFLAC__seekable_stream_encoder_finish().
*
* \param encoder An uninitialized encoder instance.
* \assert
* \code encoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__seekable_stream_encoder_finish(OggFLAC__SeekableStreamEncoder *encoder);
/** 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__seekable_stream_encoder_get_state(encoder) == OggFLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with OggFLAC__seekable_stream_encoder_get_state() to see what
* went wrong.
*/
OggFLAC_API 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 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__seekable_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__seekable_stream_encoder_get_state(encoder) == OggFLAC__SEEKABLE_STREAM_ENCODER_OK \endcode
* \retval FLAC__bool
* \c true if successful, else \c false; in this case, check the
* encoder state with OggFLAC__seekable_stream_encoder_get_state() to see what
* went wrong.
*/
OggFLAC_API FLAC__bool OggFLAC__seekable_stream_encoder_process_interleaved(OggFLAC__SeekableStreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples);
/* \} */
#ifdef __cplusplus
}
#endif
#endif

402
include/OggFLAC/stream_decoder.h
View File

@@ -32,8 +32,8 @@
#ifndef OggFLAC__STREAM_DECODER_H
#define OggFLAC__STREAM_DECODER_H
#include <stdio.h> /* for FILE */
#include "export.h"
#include "FLAC/stream_decoder.h"
#ifdef __cplusplus
@@ -95,28 +95,31 @@ typedef enum {
OggFLAC__STREAM_DECODER_OGG_ERROR,
/**< An error occurred in the underlying Ogg layer. */
OggFLAC__STREAM_DECODER_READ_ERROR,
/**< The read callback returned an error. */
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_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
OggFLAC__STREAM_DECODER_ALREADY_INITIALIZED,
/**< OggFLAC__stream_decoder_init() was called when the decoder was
* already initialized, usually because
* OggFLAC__stream_decoder_finish() was not called.
OggFLAC__STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking or the seek or tell
* callback returned an error. The decoder must be flushed with
* OggFLAC__stream_decoder_flush() or reset with
* OggFLAC__stream_decoder_reset() before decoding can continue.
*/
OggFLAC__STREAM_DECODER_INVALID_CALLBACK,
/**< The decoder was initialized before setting all the required callbacks. */
OggFLAC__STREAM_DECODER_READ_ERROR,
/**< The read callback returned an error. */
OggFLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. The decoder is in an invalid
* state and can no longer be used.
*/
OggFLAC__STREAM_DECODER_UNINITIALIZED
/**< The decoder is in the uninitialized state. */
/**< The decoder is in the uninitialized state; one of the
* OggFLAC__stream_decoder_init_*() functions must be called before samples
* can be processed.
*/
} OggFLAC__StreamDecoderState;
@@ -141,71 +144,11 @@ struct OggFLAC__StreamDecoderPrivate;
* for a detailed description.
*/
typedef struct {
FLAC__StreamDecoder super_; /* parentclass@@@@@@ */
struct OggFLAC__StreamDecoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct OggFLAC__StreamDecoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__StreamDecoder;
/** Signature for the read callback.
* See OggFLAC__stream_decoder_set_read_callback()
* and FLAC__StreamDecoderReadCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param buffer A pointer to a location for the callee to store
* data to be decoded.
* \param bytes A pointer to the size of the buffer. On entry
* to the callback, it contains the maximum number
* of bytes that may be stored in \a buffer. The
* callee must set it to the actual number of bytes
* stored before returning.
* \param client_data The callee's client data set through
* OggFLAC__stream_decoder_set_client_data().
* \retval FLAC__StreamDecoderReadStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderReadStatus (*OggFLAC__StreamDecoderReadCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/** Signature for the write callback.
* See OggFLAC__stream_decoder_set_write_callback()
* and FLAC__StreamDecoderWriteCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param frame The description of the decoded frame. See
* FLAC__Frame.
* \param buffer An array of pointers to decoded channels of data.
* Each pointer will point to an array of signed
* samples of length \a frame->header.blocksize.
* Currently, the channel order has no meaning
* except for stereo streams; in this case channel
* 0 is left and 1 is right.
* \param client_data The callee's client data set through
* OggFLAC__stream_decoder_set_client_data().
* \retval FLAC__StreamDecoderWriteStatus
* The callee's return status.
*/
typedef FLAC__StreamDecoderWriteStatus (*OggFLAC__StreamDecoderWriteCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 * const buffer[], void *client_data);
/** Signature for the metadata callback.
* See OggFLAC__stream_decoder_set_metadata_callback()
* and FLAC__StreamDecoderMetadataCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param metadata The decoded metadata block.
* \param client_data The callee's client data set through
* OggFLAC__stream_decoder_set_client_data().
*/
typedef void (*OggFLAC__StreamDecoderMetadataCallback)(const OggFLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data);
/** Signature for the error callback.
* See OggFLAC__stream_decoder_set_error_callback()
* and FLAC__StreamDecoderErrorCallback for more info.
*
* \param decoder The decoder instance calling the callback.
* \param status The error encountered by the decoder.
* \param client_data The callee's client data set through
* OggFLAC__stream_decoder_set_client_data().
*/
typedef void (*OggFLAC__StreamDecoderErrorCallback)(const OggFLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data);
/***********************************************************************
*
@@ -237,88 +180,6 @@ OggFLAC_API void OggFLAC__stream_decoder_delete(OggFLAC__StreamDecoder *decoder)
*
***********************************************************************/
/** Set the read callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_read_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_read_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderReadCallback value);
/** Set the write callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_write_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_write_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_metadata_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_metadata_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderMetadataCallback value);
/** Set the error callback.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_error_callback()
*
* \note
* The callback is mandatory and must be set before initialization.
*
* \default \c NULL
* \param decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \code value != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_error_callback(OggFLAC__StreamDecoder *decoder, OggFLAC__StreamDecoderErrorCallback value);
/** 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 decoder A decoder instance to set.
* \param value See above.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_client_data(OggFLAC__StreamDecoder *decoder, void *value);
/** Set the serial number for the Ogg stream.
* The default behavior is to use the serial number of the first Ogg
* page. Setting a serial number here will explicitly specify which
@@ -334,6 +195,19 @@ OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_client_data(OggFLAC__StreamDe
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_serial_number(OggFLAC__StreamDecoder *decoder, long serial_number);
/** Set the "MD5 signature checking" flag.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_set_md5_checking()
*
* \default \c false
* \param decoder A decoder instance to set.
* \param value Flag value (see above).
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if the decoder is already initialized, else \c true.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_set_md5_checking(OggFLAC__StreamDecoder *decoder, FLAC__bool 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()
*
@@ -457,6 +331,26 @@ OggFLAC_API FLAC__StreamDecoderState OggFLAC__stream_decoder_get_FLAC_stream_dec
*/
OggFLAC_API const char *OggFLAC__stream_decoder_get_resolved_state_string(const OggFLAC__StreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_md5_checking()
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* See above.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_get_md5_checking(const OggFLAC__StreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_total_samples()
*
* \param decoder A decoder instance to query.
* \assert
* \code decoder != NULL \endcode
* \retval unsigned
* See above.
*/
OggFLAC_API FLAC__uint64 OggFLAC__stream_decoder_get_total_samples(const OggFLAC__StreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_get_channels()
*
* \param decoder A decoder instance to query.
@@ -508,21 +402,168 @@ OggFLAC_API unsigned OggFLAC__stream_decoder_get_sample_rate(const OggFLAC__Stre
OggFLAC_API unsigned OggFLAC__stream_decoder_get_blocksize(const OggFLAC__StreamDecoder *decoder);
/** Initialize the decoder instance.
* Should be called after OggFLAC__stream_decoder_new() and
*
* This flavor of initialization sets up the decoder to decode from a stream.
* I/O is performed via callbacks to the client. For decoding from a plain file
* via filename or open FILE*, OggFLAC__stream_decoder_init_file() and
* OggFLAC__stream_decoder_init_FILE() provide a simpler interface.
*
* This function 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_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \param decoder An uninitialized decoder instance.
* \param read_callback See FLAC__StreamDecoderReadCallback. This
* pointer must not be \c NULL.
* \param seek_callback See FLAC__StreamDecoderSeekCallback. This
* pointer may be \c NULL if seeking is not
* supported. If \a seek_callback is not \c NULL then a
* \a tell_callback, \a length_callback, and \a eof_callback must also be supplied.
* Alternatively, a dummy seek callback that just
* returns \c FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param tell_callback See FLAC__StreamDecoderTellCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy tell callback that just
* returns \c FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param length_callback See FLAC__StreamDecoderLengthCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a length_callback must also be supplied.
* Alternatively, a dummy length callback that just
* returns \c FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param eof_callback See FLAC__StreamDecoderEofCallback. This
* pointer may be \c NULL if not supported by the client. If
* \a seek_callback is not \c NULL then a
* \a eof_callback must also be supplied.
* Alternatively, a dummy length callback that just
* returns \c false
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code decoder != NULL \endcode
* \retval OggFLAC__StreamDecoderState
* \c OggFLAC__STREAM_DECODER_OK if initialization was
* successful; see OggFLAC__StreamDecoderState for the meanings of other
* return values.
* \retval FLAC__StreamDecoderInitStatus
* \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamDecoderInitStatus for the meanings of other return values.
*/
OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__StreamDecoder *decoder);
OggFLAC_API FLAC__StreamDecoderInitStatus OggFLAC__stream_decoder_init_stream(
OggFLAC__StreamDecoder *decoder,
FLAC__StreamDecoderReadCallback read_callback,
FLAC__StreamDecoderSeekCallback seek_callback,
FLAC__StreamDecoderTellCallback tell_callback,
FLAC__StreamDecoderLengthCallback length_callback,
FLAC__StreamDecoderEofCallback eof_callback,
FLAC__StreamDecoderWriteCallback write_callback,
FLAC__StreamDecoderMetadataCallback metadata_callback,
FLAC__StreamDecoderErrorCallback error_callback,
void *client_data
);
/** Initialize the decoder instance.
*
* This flavor of initialization sets up the decoder to decode from a plain
* file. For non-stdio streams, you must use
* OggFLAC__stream_decoder_init_stream() and provide callbacks for the I/O.
*
* This function 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_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \param file An open Ogg FLAC file. The file should have been
* opened with mode \c "rb" and rewound. The file
* becomes owned by the decoder and should not be
* manipulated by the client while decoding.
* Unless \a file is \c stdin, it will be closed
* when OggFLAC__stream_decoder_finish() is called.
* Note however that seeking will not work when
* decoding from \c stdout since it is not seekable.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code decoder != NULL \endcode
* \code file != NULL \endcode
* \retval FLAC__StreamDecoderInitStatus
* \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamDecoderInitStatus for the meanings of other return values.
*/
OggFLAC_API FLAC__StreamDecoderInitStatus OggFLAC__stream_decoder_init_FILE(
OggFLAC__StreamDecoder *decoder,
FILE *file,
FLAC__StreamDecoderWriteCallback write_callback,
FLAC__StreamDecoderMetadataCallback metadata_callback,
FLAC__StreamDecoderErrorCallback error_callback,
void *client_data
);
/** Initialize the decoder instance.
*
* This flavor of initialization sets up the decoder to decode from a plain
* file. If POSIX fopen() semantics are not sufficient, (for example, with
* Unicode filenames on Windows), you must use
* OggFLAC__stream_decoder_init_FILE(), or OggFLAC__stream_decoder_init_stream()
* and provide callbacks for the I/O.
*
* This function 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_OK
* if initialization succeeded.
*
* \param decoder An uninitialized decoder instance.
* \param filename The name of the file to decode from. The file will
* be opened with fopen(). Use \c NULL to decode from
* \c stdin. Note that \c stdin is not seekable.
* \param write_callback See FLAC__StreamDecoderWriteCallback. This
* pointer must not be \c NULL.
* \param metadata_callback See FLAC__StreamDecoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param error_callback See FLAC__StreamDecoderErrorCallback. This
* pointer must not be \c NULL.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__StreamDecoderInitStatus
* \c FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamDecoderInitStatus for the meanings of other return values.
*/
OggFLAC_API FLAC__StreamDecoderInitStatus OggFLAC__stream_decoder_init_file(
OggFLAC__StreamDecoder *decoder,
const char *filename,
FLAC__StreamDecoderWriteCallback write_callback,
FLAC__StreamDecoderMetadataCallback metadata_callback,
FLAC__StreamDecoderErrorCallback error_callback,
void *client_data
);
/** Finish the decoding process.
* Flushes the decoding buffer, releases resources, resets the decoder
@@ -538,7 +579,7 @@ OggFLAC_API OggFLAC__StreamDecoderState OggFLAC__stream_decoder_init(OggFLAC__St
* \assert
* \code decoder != NULL \endcode
*/
OggFLAC_API void OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder);
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_finish(OggFLAC__StreamDecoder *decoder);
/** This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_flush()
*
@@ -558,7 +599,7 @@ OggFLAC_API FLAC__bool OggFLAC__stream_decoder_flush(OggFLAC__StreamDecoder *dec
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false if a memory allocation
* error occurs.
* or seek error occurs.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_reset(OggFLAC__StreamDecoder *decoder);
@@ -610,6 +651,35 @@ OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_metadata(Ogg
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_process_until_end_of_stream(OggFLAC__StreamDecoder *decoder);
/** Skip one audio frame.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_skip_single_frame()
*
* \param decoder An initialized decoder instance not in a metadata
* state.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c false if any fatal read, write, or memory allocation error
* occurred (meaning decoding must stop), or if the underlying FLAC
* stream decoder is in the FLAC__STREAM_DECODER_SEARCH_FOR_METADATA or
* FLAC__STREAM_DECODER_READ_METADATA state, else \c true; for more
* information about the decoder, check the decoder state with
* OggFLAC__stream_decoder_get_FLAC_stream_decoder_state().
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_skip_single_frame(OggFLAC__StreamDecoder *decoder);
/** Flush the input and seek to an absolute sample.
* This is inherited from FLAC__StreamDecoder; see FLAC__stream_decoder_seek_absolute().
*
* \param decoder A decoder instance.
* \param sample The target sample number to seek to.
* \assert
* \code decoder != NULL \endcode
* \retval FLAC__bool
* \c true if successful, else \c false.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_decoder_seek_absolute(OggFLAC__StreamDecoder *decoder, FLAC__uint64 sample);
/* \} */
#ifdef __cplusplus

320
include/OggFLAC/stream_encoder.h
View File

@@ -88,7 +88,13 @@ extern "C" {
typedef enum {
OggFLAC__STREAM_ENCODER_OK = 0,
/**< The encoder is in the normal OK state. */
/**< The encoder is in the normal OK state and samples can be processed. */
OggFLAC__STREAM_ENCODER_UNINITIALIZED,
/**< The encoder is in the uninitialized state; one of the
* OggFLAC__stream_encoder_init_*() functions must be called before samples
* can be processed.
*/
OggFLAC__STREAM_ENCODER_OGG_ERROR,
/**< An error occurred in the underlying Ogg layer. */
@@ -98,20 +104,16 @@ typedef enum {
* check OggFLAC__stream_encoder_get_FLAC_stream_encoder_state().
*/
OggFLAC__STREAM_ENCODER_INVALID_CALLBACK,
/**< The encoder was initialized before setting all the required callbacks. */
OggFLAC__STREAM_ENCODER_CLIENT_ERROR,
/**< One of the callbacks returned a fatal error. */
OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,
/**< Memory allocation failed. */
OggFLAC__STREAM_ENCODER_ALREADY_INITIALIZED,
/**< OggFLAC__stream_encoder_init() was called when the encoder was
* already initialized, usually because
* OggFLAC__stream_encoder_finish() was not called.
OggFLAC__STREAM_ENCODER_IO_ERROR,
/**< An I/O error occurred while opening/reading/writing a file.
* Check \c errno.
*/
OggFLAC__STREAM_ENCODER_UNINITIALIZED
/**< The encoder is in the uninitialized state. */
OggFLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR
/**< Memory allocation failed. */
} OggFLAC__StreamEncoderState;
@@ -123,6 +125,32 @@ typedef enum {
extern OggFLAC_API const char * const OggFLAC__StreamEncoderStateString[];
/** Return values for the OggFLAC__StreamEncoder read callback.
*/
typedef enum {
OggFLAC__STREAM_ENCODER_READ_STATUS_CONTINUE,
/**< The read was OK and decoding can continue. */
OggFLAC__STREAM_ENCODER_READ_STATUS_END_OF_STREAM,
/**< The read was attempted at the end of the stream. */
OggFLAC__STREAM_ENCODER_READ_STATUS_ABORT,
/**< An unrecoverable error occurred. */
OggFLAC__STREAM_ENCODER_READ_STATUS_UNSUPPORTED
/**< Client does not support reading back from the output. */
} OggFLAC__StreamEncoderReadStatus;
/** Maps a OggFLAC__StreamEncoderReadStatus to a C string.
*
* Using a OggFLAC__StreamEncoderReadStatus as the index to this array
* will give the string equivalent. The contents should not be modified.
*/
extern OggFLAC_API const char * const OggFLAC__StreamEncoderReadStatusString[];
/***********************************************************************
*
* class OggFLAC__StreamEncoder
@@ -136,38 +164,42 @@ struct OggFLAC__StreamEncoderPrivate;
* for a detailed description.
*/
typedef struct {
FLAC__StreamEncoder super_; /* parentclass@@@@@@ */
struct OggFLAC__StreamEncoderProtected *protected_; /* avoid the C++ keyword 'protected' */
struct OggFLAC__StreamEncoderPrivate *private_; /* avoid the C++ keyword 'private' */
} OggFLAC__StreamEncoder;
/** Signature for the write callback.
* See OggFLAC__stream_encoder_set_write_callback()
* and FLAC__StreamEncoderWriteCallback for more info.
/** Signature for the read callback.
*
* A function pointer matching this signature must be passed to
* OggFLAC__stream_encoder_init_stream() if seeking is supported.
* The supplied function will be called when the encoder needs to read back
* encoded data. This happens during the metadata callback, when the encoder
* has to read, modify, and rewrite the metadata (e.g. seekpoints) gathered
* while encoding. 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__StreamEncoderReadStatus.
*
* \note In general, FLAC__StreamEncoder functions which change the
* state should not be called on the \a encoder while in the callback.
*
* \param encoder The encoder instance calling the callback.
* \param buffer An array of encoded data of length \a bytes.
* \param bytes The byte length of \a buffer.
* \param samples The number of samples encoded by \a buffer.
* \c 0 has a special meaning; see
* OggFLAC__stream_encoder_set_write_callback().
* \param current_frame The number of current frame being encoded.
* \param buffer A pointer to a location for the callee to store
* data to be encoded.
* \param bytes A pointer to the size of the buffer. On entry
* to the callback, it contains the maximum number
* of bytes that may be stored in \a buffer. The
* callee must set it to the actual number of bytes
* stored (0 in case of error or end-of-stream) before
* returning.
* \param client_data The callee's client data set through
* OggFLAC__stream_encoder_set_client_data().
* \retval FLAC__StreamEncoderWriteStatus
* \retval OggFLAC__StreamEncoderReadStatus
* The callee's return status.
*/
typedef FLAC__StreamEncoderWriteStatus (*OggFLAC__StreamEncoderWriteCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data);
/** Signature for the metadata callback.
* See OggFLAC__stream_encoder_set_metadata_callback()
* and FLAC__stream_encoder_set_metadata_callback() for more info.
*
* \param encoder The encoder instance calling the callback.
* \param metadata The final populated STREAMINFO block.
* \param client_data The callee's client data set through
* FLAC__stream_encoder_set_client_data().
*/
typedef void (*OggFLAC__StreamEncoderMetadataCallback)(const OggFLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data);
typedef OggFLAC__StreamEncoderReadStatus (*OggFLAC__StreamEncoderReadCallback)(const OggFLAC__StreamEncoder *encoder, FLAC__byte buffer[], unsigned *bytes, void *client_data);
/***********************************************************************
@@ -460,63 +492,6 @@ OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_total_samples_estimate(OggFLA
*/
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata(OggFLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks);
/** Set the write callback.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_write_callback().
*
* \note
* Unlike the FLAC stream encoder write callback, the Ogg stream
* encoder write callback will be called twice when writing audio
* frames; once for the page header, and once for the page body.
* When writing the page header, the \a samples argument to the
* write callback will be \c 0.
*
* \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.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_write_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderWriteCallback value);
/** Set the metadata callback.
* This is inherited from FLAC__StreamEncoder; see
* FLAC__stream_encoder_set_metadata_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.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_metadata_callback(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderMetadataCallback value);
/** 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.
*/
OggFLAC_API FLAC__bool OggFLAC__stream_encoder_set_client_data(OggFLAC__StreamEncoder *encoder, void *value);
/** Get the current encoder state.
*
* \param encoder An encoder instance to query.
@@ -780,6 +755,169 @@ OggFLAC_API FLAC__uint64 OggFLAC__stream_encoder_get_total_samples_estimate(cons
*/
OggFLAC_API OggFLAC__StreamEncoderState OggFLAC__stream_encoder_init(OggFLAC__StreamEncoder *encoder);
/** Initialize the encoder instance.
*
* This flavor of initialization sets up the encoder to encode to a stream.
* I/O is performed via callbacks to the client. For encoding to a plain file
* via filename or open \c FILE*, OggFLAC__stream_encoder_init_file() and
* OggFLAC__stream_encoder_init_FILE() provide a simpler interface.
*
* This function 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().
* initialization succeeded.
*
* The call to OggFLAC__stream_encoder_init_stream() currently will also immediately
* call the write callback several times, once with the \c fLaC signature,
* and once for each encoded metadata block.
*
* \note
* Unlike the FLAC stream encoder write callback, the Ogg stream
* encoder write callback will be called twice when writing each audio
* frame; once for the page header, and once for the page body.
* When writing the page header, the \a samples argument to the
* write callback will be \c 0.
*
* \param encoder An uninitialized encoder instance.
* \param read_callback See OggFLAC__StreamEncoderReadCallback. This
* pointer must not be \c NULL if \a seek_callback
* is non-NULL since they are both needed to be
* able to write data back to the Ogg FLAC stream
* in the post-encode phase.
* \param write_callback See FLAC__StreamEncoderWriteCallback. This
* pointer must not be \c NULL.
* \param seek_callback See FLAC__StreamEncoderSeekCallback. This
* pointer may be \c NULL if seeking is not
* supported. The encoder uses seeking to go back
* and write some some stream statistics to the
* STREAMINFO block; this is recommended but not
* necessary to create a valid FLAC stream. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy seek callback that just
* returns \c FLAC__STREAM_ENCODER_SEEK_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param tell_callback See FLAC__StreamEncoderTellCallback. This
* pointer may be \c NULL if seeking is not
* supported. If \a seek_callback is \c NULL then
* this argument will be ignored. If
* \a seek_callback is not \c NULL then a
* \a tell_callback must also be supplied.
* Alternatively, a dummy tell callback that just
* returns \c FLAC__STREAM_ENCODER_TELL_STATUS_UNSUPPORTED
* may also be supplied, all though this is slightly
* less efficient for the decoder.
* \param metadata_callback See FLAC__StreamEncoderMetadataCallback. This
* pointer may be \c NULL if the callback is not
* desired. If the client provides a seek callback,
* this function is not necessary as the encoder
* will automatically seek back and update the
* STREAMINFO block. It may also be \c NULL if the
* client does not support seeking, since it will
* have no way of going back to update the
* STREAMINFO. However the client can still supply
* a callback if it would like to know the details
* from the STREAMINFO.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderInitStatus
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
*/
OggFLAC_API FLAC__StreamEncoderInitStatus OggFLAC__stream_encoder_init_stream(OggFLAC__StreamEncoder *encoder, OggFLAC__StreamEncoderReadCallback read_callback, FLAC__StreamEncoderWriteCallback write_callback, FLAC__StreamEncoderSeekCallback seek_callback, FLAC__StreamEncoderTellCallback tell_callback, FLAC__StreamEncoderMetadataCallback metadata_callback, void *client_data);
/** Initialize the encoder instance.
*
* This flavor of initialization sets up the encoder to encode to a plain
* file. For non-stdio streams, you must use
* OggFLAC__stream_encoder_init_stream() and provide callbacks for the I/O.
*
* This function 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().
* initialization succeeded.
*
* The call to OggFLAC__stream_encoder_init_stream() currently will also immediately
* call the write callback several times, once with the \c fLaC signature,
* and once for each encoded metadata block.
*
* \note
* Unlike the FLAC stream encoder write callback, the Ogg stream
* encoder write callback will be called twice when writing each audio
* frame; once for the page header, and once for the page body.
* When writing the page header, the \a samples argument to the
* write callback will be \c 0.
*
* \param encoder An uninitialized encoder instance.
* \param file An open file. The file should have been opened
* with mode \c "w+b" and rewound. The file
* becomes owned by the encoder and should not be
* manipulated by the client while encoding.
* Unless \a file is \c stdout, it will be closed
* when OggFLAC__stream_encoder_finish() is called.
* Note however that a proper SEEKTABLE cannot be
* created when encoding to \c stdout since it is
* not seekable.
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code encoder != NULL \endcode
* \code file != NULL \endcode
* \retval FLAC__StreamEncoderInitStatus
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
*/
OggFLAC_API FLAC__StreamEncoderInitStatus OggFLAC__stream_encoder_init_FILE(OggFLAC__StreamEncoder *encoder, FILE *file, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
/** Initialize the encoder instance.
*
* This flavor of initialization sets up the encoder to encode to a plain
* file. If POSIX fopen() semantics are not sufficient (for example,
* with Unicode filenames on Windows), you must use
* OggFLAC__stream_encodeR_init_FILE(), or OggFLAC__stream_encoder_init_stream()
* and provide callbacks for the I/O.
*
* This function 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().
* initialization succeeded.
*
* The call to OggFLAC__stream_encoder_init_stream() currently will also immediately
* call the write callback several times, once with the \c fLaC signature,
* and once for each encoded metadata block.
*
* \note
* Unlike the FLAC stream encoder write callback, the Ogg stream
* encoder write callback will be called twice when writing each audio
* frame; once for the page header, and once for the page body.
* When writing the page header, the \a samples argument to the
* write callback will be \c 0.
*
* \param encoder An uninitialized encoder instance.
* \param filename The name of the file to encode to. The file will
* be opened with fopen(). Use \c NULL to encode to
* \c stdout. Note however that a proper SEEKTABLE
* cannot be created when encoding to \c stdout since
* it is not seekable.
* \param progress_callback See FLAC__StreamEncoderProgressCallback. This
* pointer may be \c NULL if the callback is not
* desired.
* \param client_data This value will be supplied to callbacks in their
* \a client_data argument.
* \assert
* \code encoder != NULL \endcode
* \retval FLAC__StreamEncoderInitStatus
* \c FLAC__STREAM_ENCODER_INIT_STATUS_OK if initialization was successful;
* see FLAC__StreamEncoderInitStatus for the meanings of other return values.
*/
OggFLAC_API FLAC__StreamEncoderInitStatus OggFLAC__stream_encoder_init_file(OggFLAC__StreamEncoder *encoder, const char *filename, FLAC__StreamEncoderProgressCallback progress_callback, void *client_data);
/** Finish the encoding process.
* Flushes the encoding buffer, releases resources, resets the encoder
* settings to their defaults, and returns the encoder state to

13
include/test_libs_common/Makefile.am Normal file
View File

@@ -0,0 +1,13 @@
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
if FLaC__HAS_OGG
OGGFLAC_DIST = \
file_utils_oggflac.h
endif
EXTRA_DIST = \
file_utils_flac.h \
metadata_utils.h \
$(OGGFLAC_DIST)

32
include/test_libs_common/file_utils_flac.h Normal file
View File

@@ -0,0 +1,32 @@
/* test_libFLAC - Unit tester for libFLAC
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
#ifndef FLAC__TEST_LIBFLAC_FILE_UTILS_H
#define FLAC__TEST_LIBFLAC_FILE_UTILS_H
/* needed because of off_t */
#if HAVE_CONFIG_H
# include <config.h>
#endif
#include "FLAC/format.h"
#include <sys/types.h> /* for off_t */
FLAC__bool file_utils__generate_flacfile(const char *output_filename, off_t *output_filesize, unsigned length, const FLAC__StreamMetadata *streaminfo, FLAC__StreamMetadata **metadata, unsigned num_metadata);
#endif

34
include/test_libs_common/file_utils_oggflac.h Normal file
View File

@@ -0,0 +1,34 @@
/* test_libOggFLAC - Unit tester for libOggFLAC
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
#ifndef OggFLAC__TEST_LIBOGGFLAC_FILE_UTILS_H
#define OggFLAC__TEST_LIBOGGFLAC_FILE_UTILS_H
/* needed because of off_t */
#if HAVE_CONFIG_H
# include <config.h>
#endif
#include "FLAC/format.h"
#include <sys/types.h> /* for off_t */
extern const long file_utils__serial_number;
FLAC__bool file_utils__generate_oggflacfile(const char *output_filename, off_t *output_filesize, unsigned length, const FLAC__StreamMetadata *streaminfo, FLAC__StreamMetadata **metadata, unsigned num_metadata);
#endif

69
include/test_libs_common/metadata_utils.h Normal file
View File

@@ -0,0 +1,69 @@
/* test_libFLAC - Unit tester for libFLAC
* Copyright (C) 2002,2003,2004,2005,2006 Josh Coalson
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*/
#ifndef FLAC__TEST_LIBFLAC_METADATA_H
#define FLAC__TEST_LIBFLAC_METADATA_H
/*
* These are not tests, just utility functions used by the metadata tests
*/
#include "FLAC/format.h"
#include <stdio.h>
#include <stdlib.h> /* for malloc() */
#include <string.h> /* for memcmp() */
FLAC__bool mutils__compare_block_data_streaminfo(const FLAC__StreamMetadata_StreamInfo *block, const FLAC__StreamMetadata_StreamInfo *blockcopy);
FLAC__bool mutils__compare_block_data_padding(const FLAC__StreamMetadata_Padding *block, const FLAC__StreamMetadata_Padding *blockcopy, unsigned block_length);
FLAC__bool mutils__compare_block_data_application(const FLAC__StreamMetadata_Application *block, const FLAC__StreamMetadata_Application *blockcopy, unsigned block_length);
FLAC__bool mutils__compare_block_data_seektable(const FLAC__StreamMetadata_SeekTable *block, const FLAC__StreamMetadata_SeekTable *blockcopy);
FLAC__bool mutils__compare_block_data_vorbiscomment(const FLAC__StreamMetadata_VorbisComment *block, const FLAC__StreamMetadata_VorbisComment *blockcopy);
FLAC__bool mutils__compare_block_data_cuesheet(const FLAC__StreamMetadata_CueSheet *block, const FLAC__StreamMetadata_CueSheet *blockcopy);
FLAC__bool mutils__compare_block_data_unknown(const FLAC__StreamMetadata_Unknown *block, const FLAC__StreamMetadata_Unknown *blockcopy, unsigned block_length);
FLAC__bool mutils__compare_block(const FLAC__StreamMetadata *block, const FLAC__StreamMetadata *blockcopy);
void mutils__init_metadata_blocks(
FLAC__StreamMetadata *streaminfo,
FLAC__StreamMetadata *padding,
FLAC__StreamMetadata *seektable,
FLAC__StreamMetadata *application1,
FLAC__StreamMetadata *application2,
FLAC__StreamMetadata *vorbiscomment,
FLAC__StreamMetadata *cuesheet,
FLAC__StreamMetadata *unknown
);
void mutils__free_metadata_blocks(
FLAC__StreamMetadata *streaminfo,
FLAC__StreamMetadata *padding,
FLAC__StreamMetadata *seektable,
FLAC__StreamMetadata *application1,
FLAC__StreamMetadata *application2,
FLAC__StreamMetadata *vorbiscomment,
FLAC__StreamMetadata *cuesheet,
FLAC__StreamMetadata *unknown
);
#endif