Commit 6b21f667 authored by Josh Coalson's avatar Josh Coalson

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

merge down from merged-API-layer branch: cvs -q up -dP -j API_LAYER_MERGING_BASELINE -j API_LAYER_MERGING_BRANCH
parent 461f3eb2
......@@ -81,6 +81,9 @@ Package=<4>
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name plugin_common_static
End Project Dependency
Begin Project Dependency
......@@ -159,6 +162,9 @@ Package=<4>
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name plugin_common_static
End Project Dependency
Begin Project Dependency
......@@ -498,6 +504,24 @@ Package=<4>
###############################################################################
Project: "test_libs_common"=.\src\test_libs_common\test_libs_common_static.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
}}}
###############################################################################
Project: "test_libFLAC"=.\src\test_libFLAC\test_libFLAC.dsp - Package Owner=<4>
Package=<5>
......@@ -509,6 +533,9 @@ Package=<4>
Begin Project Dependency
Project_Dep_Name libFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
}}}
###############################################################################
......@@ -524,6 +551,9 @@ Package=<4>
Begin Project Dependency
Project_Dep_Name libFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
}}}
###############################################################################
......@@ -539,6 +569,9 @@ Package=<4>
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
}}}
###############################################################################
......@@ -554,6 +587,9 @@ Package=<4>
Begin Project Dependency
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
}}}
###############################################################################
......
......@@ -241,17 +241,18 @@ configure.in and src/libFLAC/Makefile.am; the following dependency
graph shows which modules may be pruned without breaking things
further down:
file_encoder.h
stream_encoder.h
format.h
stream_encoder.h
stream_decoder.h
format.h
file_decoder.h
seekable_stream_decoder.h
stream_decoder.h
format.h
stream_decoder.h
format.h
metadata.h
format.h
In other words, for pure decoding applications, both the stream encoder
and metadata editing interfaces can be safely removed.
There is a section dedicated to embedded use in the libFLAC API
HTML documentation (see doc/html/api/index.html).
......@@ -314,6 +314,7 @@ AC_CONFIG_FILES([ \
src/share/utf8/Makefile \
src/test_grabbag/Makefile \
src/test_grabbag/cuesheet/Makefile \
src/test_libs_common/Makefile \
src/test_libFLAC/Makefile \
src/test_libFLAC++/Makefile \
src/test_libOggFLAC/Makefile \
......@@ -327,6 +328,7 @@ AC_CONFIG_FILES([ \
include/OggFLAC++/Makefile \
include/share/Makefile \
include/share/grabbag/Makefile \
include/test_libs_common/Makefile \
doc/Makefile \
doc/html/Makefile \
doc/html/images/Makefile \
......@@ -334,6 +336,8 @@ AC_CONFIG_FILES([ \
man/Makefile \
test/Makefile \
test/cuesheets/Makefile \
test/flac-to-flac-metadata-test-files/Makefile \
test/metaflac-test-files/Makefile \
build/Makefile \
obj/Makefile \
obj/debug/Makefile \
......
......@@ -53,7 +53,7 @@
</div>
<div class="box_header"></div>
<div class="box_body">
This is an informal changelog, a summary of changes in each release. Particulary important for developers is the precise description of changes to the library interfaces.
This is an informal changelog, a summary of changes in each release. Particulary important for developers is the precise description of changes to the library interfaces. See also the <a href="http://flac.sourceforge.net/api/group__porting.html">porting guide</a> for specific instructions on porting to newer versions of FLAC.
<br /><br />
......@@ -68,6 +68,7 @@
<li>Large file (&gt;2GB) support everywhere</li>
<li>Much better recovery for corrupted files</li>
<li><span class="commandname">flac</span> now supports FLAC as input to the encoder (i.e. can re-encode FLAC to FLAC) and preserve all the metadata like tags, etc.</li>
<li>In the developer libraries, the interface has been simplfied by merging the three decoding layers into a single class; ditto for the encoders.</li>
</ul>
</li>
<li>
......@@ -134,12 +135,19 @@
</ul>
</li>
<li>
Interface changes:
Interface changes (see also the <a href="http://flac.sourceforge.net/api/group__porting__1__1__2__to__1__1__3.html">porting guide</a> for specific instructions on porting to FLAC 1.1.3):
<ul>
<li>
all libraries;
<ul>
<li>Merged seekable stream decoder and file decoder into the stream decoder.</li>
<li>Merged seekable stream encoder and file encoder into the stream encoder.</li>
</ul>
</li>
<li>
libFLAC:
<ul>
<li><b>Added</b> FLAC__*_encoder_set_apodization()</li>
<li><b>Added</b> FLAC__stream_encoder_set_apodization()</li>
<li><b>Added</b> FLAC__metadata_object_cuesheet_calculate_cddb_id()</li>
<li><b>Added</b> FLAC__metadata_get_cuesheet()</li>
<li><b>Changed</b> FLAC__StreamDecoderState: removed state FLAC__STREAM_DECODER_UNPARSEABLE_STREAM</li>
......@@ -150,7 +158,7 @@
<li>
libFLAC++:
<ul>
<li><b>Added</b> FLAC::*::Encoder::set_apodization()</li>
<li><b>Added</b> FLAC::Encoder::Stream::set_apodization()</li>
<li><b>Added</b> FLAC::Metadata::CueSheet::calculate_cddb_id()</li>
<li><b>Added</b> FLAC::Metadata::get_cuesheet()</li>
</ul>
......@@ -158,7 +166,7 @@
<li>
libOggFLAC:
<ul>
<li><b>Added</b> OggFLAC__*_encoder_set_apodization()</li>
<li><b>Added</b> OggFLAC__stream_encoder_set_apodization()</li>
<li><b>Added</b> OggFLAC__metadata_object_cuesheet_calculate_cddb_id()</li>
<li><b>Added</b> OggFLAC__metadata_get_cuesheet()</li>
</ul>
......@@ -166,7 +174,7 @@
<li>
libOggFLAC++:
<ul>
<li><b>Added</b> OggFLAC::*::Encoder::set_apodization()</li>
<li><b>Added</b> OggFLAC::Encoder::Stream::set_apodization()</li>
<li><b>Added</b> OggFLAC::Metadata::CueSheet::calculate_cddb_id()</li>
<li><b>Added</b> OggFLAC::Metadata::get_cuesheet()</li>
</ul>
......
......@@ -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();
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;
/* \} */
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; ///< 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(); ///< See FLAC__stream_decoder_finish()
void finish();
bool flush(); ///< See FLAC__stream_decoder_flush()
bool reset(); ///< See FLAC__stream_decoder_reset()
bool flush();
bool reset();
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 process_single();
bool process_until_end_of_metadata();
bool process_until_end_of_stream();
bool 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
/** \defgroup flacpp_file_decoder FLAC++/decoder.h: file decoder class
* \ingroup flacpp_decoder
*
* \brief
* This class wraps the ::FLAC__SeekableStreamDecoder.
* This class wraps the ::FLAC__StreamDecoder.
*
* See the \link flac_seekable_stream_decoder libFLAC seekable stream decoder module \endlink.
* See the \link flac_stream_decoder libFLAC stream decoder module \endlink
* for basic usage.
*
* \{
*/
/** 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
/** This class wraps the ::FLAC__StreamDecoder. If you are
* not decoding from a file, you may need to use
* FLAC::Decoder::Stream.
*
* \brief
* This class wraps the ::FLAC__FileDecoder.
*
* See the \link flac_file_decoder libFLAC file decoder module \endlink.
* 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.
*
* \{
*/
/** This class wraps the ::FLAC__FileDecoder.
* 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);