Skip to content

GitLab

F
flac
Commit 8da98c89 authored by Josh Coalson's avatar Josh Coalson
Browse files
Options

merge libOggFLAC into libFLAC and libOggFLAC++ into FLAC++; documentation still needs work

parent 03dbb26a
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2580 additions and 12226 deletions
FLAC.dsw
View file @ 8da98c89
......@@ -69,18 +69,6 @@ Package=<4>
Project_Dep_Name libFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_dynamic
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC++_dynamic
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
Begin Project Dependency
......@@ -102,12 +90,6 @@ Package=<4>
Project_Dep_Name test_libFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_seeking
End Project Dependency
Begin Project Dependency
......@@ -159,12 +141,6 @@ Package=<4>
Project_Dep_Name libFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC++_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libs_common_static
End Project Dependency
Begin Project Dependency
......@@ -186,12 +162,6 @@ Package=<4>
Project_Dep_Name test_libFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_libOggFLAC++
End Project Dependency
Begin Project Dependency
Project_Dep_Name test_seeking
End Project Dependency
Begin Project Dependency
......@@ -225,9 +195,6 @@ Package=<4>
Project_Dep_Name libFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name utf8_static
End Project Dependency
}}}
......@@ -384,72 +351,6 @@ Package=<4>
###############################################################################
Project: "libOggFLAC_dynamic"=.\src\libOggFLAC\libOggFLAC_dynamic.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libFLAC_dynamic
End Project Dependency
}}}
###############################################################################
Project: "libOggFLAC_static"=.\src\libOggFLAC\libOggFLAC_static.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libFLAC_static
End Project Dependency
}}}
###############################################################################
Project: "libOggFLAC++_dynamic"=".\src\libOggFLAC++\libOggFLAC++_dynamic.dsp" - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libOggFLAC_dynamic
End Project Dependency
Begin Project Dependency
Project_Dep_Name libFLAC++_dynamic
End Project Dependency
}}}
###############################################################################
Project: "libOggFLAC++_static"=".\src\libOggFLAC++\libOggFLAC++_static.dsp" - Package Owner=<4>
Package=<5>
{{{
}}}
Package=<4>
{{{
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libFLAC++_static
End Project Dependency
}}}
###############################################################################
Project: "metaflac"=.\src\metaflac\metaflac.dsp - Package Owner=<4>
Package=<5>
......@@ -536,9 +437,6 @@ Package=<4>
Begin Project Dependency
Project_Dep_Name libFLAC_static
End Project Dependency
Begin Project Dependency
Project_Dep_Name libOggFLAC_static
End Project Dependency
}}}
###############################################################################
......@@ -579,42 +477,6 @@ Package=<4>
###############################################################################
Project: "test_libOggFLAC"=.\src\test_libOggFLAC\test_libOggFLAC.dsp - Package Owner=<4>
Package=<5>
{{{
}}}
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
}}}
###############################################################################
Project: "test_libOggFLAC++"=".\src\test_libOggFLAC++\test_libOggFLAC++.dsp" - Package Owner=<4>
Package=<5>
{{{
}}}
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
}}}
###############################################################################
Project: "test_seeking"=.\src\test_seeking\test_seeking.dsp - Package Owner=<4>
Package=<5>
......
Makefile.lite
View file @ 8da98c89
......@@ -30,7 +30,7 @@
topdir = .
.PHONY: all doc src libFLAC libFLAC++ libOggFLAC libOggFLAC++ share plugin_common plugin_xmms flac metaflac test_grabbag test_libFLAC test_libFLAC++ test_libOggFLAC test_libOggFLAC++ test_seeking test_streams
.PHONY: all doc src libFLAC libFLAC++ share plugin_common plugin_xmms flac metaflac test_grabbag test_libFLAC test_libFLAC++ test_seeking test_streams
all: doc src
DEFAULT_CONFIG = release
......@@ -57,16 +57,10 @@ libFLAC:
libFLAC++: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
libOggFLAC: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
libOggFLAC++: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
share: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
flac: libFLAC libOggFLAC share
flac: libFLAC share
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
metaflac: libFLAC share
......@@ -78,7 +72,7 @@ plugin_common: libFLAC
plugin_xmms: libFLAC plugin_common
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_seeking: libFLAC libOggFLAC
test_seeking: libFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_streams: libFLAC
......@@ -93,12 +87,6 @@ test_libFLAC: libFLAC
test_libFLAC++: libFLAC libFLAC++
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_libOggFLAC: libFLAC libOggFLAC
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test_libOggFLAC++: libFLAC libOggFLAC libOggFLAC++
(cd src/$@ ; $(MAKE) -f Makefile.lite $(CONFIG))
test: debug
(cd test ; $(MAKE) -f Makefile.lite debug)
......
README
View file @ 8da98c89
......@@ -22,17 +22,15 @@ codec developed by Josh Coalson.
FLAC is comprised of
* `libFLAC', a library which implements reference encoders and
decoders, and a metadata interface
decoders for native FLAC and Ogg FLAC, and a metadata interface
* `libFLAC++', a C++ object wrapper library around libFLAC
* `libOggFLAC' and `libOggFLAC++', which provide encoders and
decoders for FLAC streams in an Ogg container
* `flac', a command-line program for encoding and decoding files
* `metaflac', a command-line program for viewing and editing FLAC
metadata
* player plugins for XMMS and Winamp
* user and API documentation
The libraries (libFLAC, libFLAC++, libOggFLAC, and libOggFLAC++) are
The libraries (libFLAC, libFLAC++) are
licensed under Xiph.org's BSD-like license (see COPYING.Xiph). All other
programs and plugins are licensed under the GNU General Public License
(see COPYING.GPL). The documentation is licensed under the GNU Free
......
configure.in
View file @ 8da98c89
......@@ -289,11 +289,6 @@ AC_CONFIG_FILES([ \
src/libFLAC/include/private/Makefile \
src/libFLAC/include/protected/Makefile \
src/libFLAC++/Makefile \
src/libOggFLAC/Makefile \
src/libOggFLAC/include/Makefile \
src/libOggFLAC/include/private/Makefile \
src/libOggFLAC/include/protected/Makefile \
src/libOggFLAC++/Makefile \
src/flac/Makefile \
src/metaflac/Makefile \
src/monkeys_audio_utilities/Makefile \
......@@ -318,15 +313,11 @@ AC_CONFIG_FILES([ \
src/test_libs_common/Makefile \
src/test_libFLAC/Makefile \
src/test_libFLAC++/Makefile \
src/test_libOggFLAC/Makefile \
src/test_libOggFLAC++/Makefile \
src/test_seeking/Makefile \
src/test_streams/Makefile \
include/Makefile \
include/FLAC/Makefile \
include/FLAC++/Makefile \
include/OggFLAC/Makefile \
include/OggFLAC++/Makefile \
include/share/Makefile \
include/share/grabbag/Makefile \
include/test_libs_common/Makefile \
......
doc/html/changelog.html
View file @ 8da98c89
......@@ -72,7 +72,7 @@
<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>New <a href="format.html#def_PICTURE"><span class="code">PICTURE</span></a> metadata block for storing things like cover art, new <span class="argument"><a href="documentation.html#flac_options_picture">--picture</a></span> option to <span class="commandname">flac</span> and <span class="argument"><a href="documentation.html#metaflac_shorthand_import_picture">--import-picture</a></span> option to <span class="commandname">metaflac</span> for importing pictures, and metadata API <a href="api/group__flac__metadata__level0.html#ga3">additions</a> for searching for suitable pictures based on type, size and color constraints.</li>
<li>Support for new <tt>REPLAYGAIN_REFERENCE_LOUDNESS</tt> tag.</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>
<li>In the developer libraries, the interface has been simplfied by merging the three decoding layers into a single class; ditto for the encoders. Also, libOggFLAC has been merged into libFLAC and libOggFLAC++ has been merged into libFLAC++ so there is a single API supporting both native FLAC and Ogg FLAC.</li>
</ul>
</li>
<li>
......@@ -154,6 +154,8 @@
<li>
libraries:
<ul>
<li>Merged libOggFLAC into libFLAC; both formats are now supporte through the same API.</li>
<li>Merged libOggFLAC++ into libFLAC++; both formats are now supporte through the same API.</li>
<li>libFLAC: Improved compression with no impact on FLAC format or decoding time by adding a windowing stage before LPC analysis.</li>
<li>libFLAC: Fixed a bug in cuesheet parsing where it would return an error if the last line of the cuesheet did not end with a newline.</li>
<li>libFLAC: Fixed UTF-8 decoder to disallow non-shortest-form and surrogate sequences (see <a href="http://www.unicode.org/versions/corrigendum1.html">here</a>).</li>
......@@ -166,6 +168,8 @@
<li>
all libraries;
<ul>
<li>Merged libOggFLAC into libFLAC; both formats are now supporte through the same API.</li>
<li>Merged libOggFLAC++ into libFLAC++; both formats are now supporte through the same API.</li>
<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>
<li>Added #defines for the API version number to make porting easier; see <tt>include/lib*FLAC*/export.h</tt>.</li>
......@@ -196,19 +200,13 @@
<li>
libOggFLAC:
<ul>
<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>
<li><b>Added</b> OggFLAC__metadata_get_picture()</li>
<li>Merged into libFLAC.</li>
</ul>
</li>
<li>
libOggFLAC++:
<ul>
<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>
<li><b>Added</b> OggFLAC::Metadata::get_picture()</li>
<li>Merged into libFLAC++.</li>
</ul>
</li>
</ul>
......
include/FLAC++/decoder.h
View file @ 8da98c89
......@@ -129,6 +129,7 @@ namespace FLAC {
inline operator bool() const { return is_valid(); }
//@}
virtual bool set_serial_number(long value); ///< See FLAC__stream_decoder_set_serial_number()
virtual bool set_md5_checking(bool value); ///< See FLAC__stream_decoder_set_md5_checking()
virtual bool set_metadata_respond(::FLAC__MetadataType type); ///< See FLAC__stream_decoder_set_metadata_respond()
virtual bool set_metadata_respond_application(const FLAC__byte id[4]); ///< See FLAC__stream_decoder_set_metadata_respond_application()
......@@ -147,13 +148,8 @@ namespace FLAC {
virtual unsigned get_sample_rate() const; ///< See FLAC__stream_decoder_get_sample_rate()
virtual 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().
*/
virtual ::FLAC__StreamDecoderInitStatus init();
virtual ::FLAC__StreamDecoderInitStatus init(); ///< Seek FLAC__stream_decoder_init_stream()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(); ///< Seek FLAC__stream_decoder_init_ogg_stream()
virtual void finish(); ///< See FLAC__stream_decoder_finish()
......@@ -250,18 +246,12 @@ namespace FLAC {
File();
virtual ~File();
//@{
/** 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);
//@}
virtual ::FLAC__StreamDecoderInitStatus init(FILE *file); ///< See FLAC__stream_decoder_init_FILE()
virtual ::FLAC__StreamDecoderInitStatus init(const char *filename); ///< See FLAC__stream_decoder_init_file()
virtual ::FLAC__StreamDecoderInitStatus init(const std::string &filename); ///< See FLAC__stream_decoder_init_file()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(FILE *file); ///< See FLAC__stream_decoder_init_ogg_FILE()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(const char *filename); ///< See FLAC__stream_decoder_init_ogg_file()
virtual ::FLAC__StreamDecoderInitStatus init_ogg(const std::string &filename); ///< See FLAC__stream_decoder_init_ogg_file()
protected:
// 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);
......
include/FLAC++/encoder.h
View file @ 8da98c89
......@@ -56,7 +56,7 @@
* This module describes the encoder layers provided by libFLAC++.
*
* The libFLAC++ encoder classes are object wrappers around their
* counterparts in libFLAC. All decoding layers available in
* counterparts in libFLAC. All encoding 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.
*
......@@ -132,6 +132,7 @@ namespace FLAC {
inline operator bool() const { return is_valid(); }
//@}
virtual bool set_serial_number(long value); ///< See FLAC__stream_encoder_set_serial_number()
virtual bool set_verify(bool value); ///< See FLAC__stream_encoder_set_verify()
virtual bool set_streamable_subset(bool value); ///< See FLAC__stream_encoder_set_streamable_subset()
virtual bool set_do_mid_side_stereo(bool value); ///< See FLAC__stream_encoder_set_do_mid_side_stereo()
......@@ -175,19 +176,17 @@ namespace FLAC {
virtual unsigned get_rice_parameter_search_dist() const; ///< See FLAC__stream_encoder_get_rice_parameter_search_dist()
virtual FLAC__uint64 get_total_samples_estimate() const; ///< See FLAC__stream_encoder_get_total_samples_estimate()
/** 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().
*/
virtual ::FLAC__StreamEncoderInitStatus init();
virtual ::FLAC__StreamEncoderInitStatus init(); ///< See FLAC__stream_encoder_init_stream()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(); ///< See FLAC__stream_encoder_init_ogg_stream()
virtual void finish(); ///< See FLAC__stream_encoder_finish()
virtual bool process(const FLAC__int32 * const buffer[], unsigned samples); ///< See FLAC__stream_encoder_process()
virtual bool process_interleaved(const FLAC__int32 buffer[], unsigned samples); ///< See FLAC__stream_encoder_process_interleaved()
protected:
/// See FLAC__StreamEncoderReadCallback
virtual ::FLAC__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;
......@@ -209,6 +208,7 @@ namespace FLAC {
::FLAC__StreamEncoder *encoder_;
static ::FLAC__StreamEncoderReadStatus read_callback_(const ::FLAC__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);
......@@ -256,18 +256,12 @@ namespace FLAC {
File();
virtual ~File();
//@{
/* 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().
*/
::FLAC__StreamEncoderInitStatus init(FILE *file);
::FLAC__StreamEncoderInitStatus init(const char *filename);
::FLAC__StreamEncoderInitStatus init(const std::string &filename);
//@}
virtual ::FLAC__StreamEncoderInitStatus init(FILE *file); ///< See FLAC__stream_encoder_init_FILE()
virtual ::FLAC__StreamEncoderInitStatus init(const char *filename); ///< See FLAC__stream_encoder_init_file()
virtual ::FLAC__StreamEncoderInitStatus init(const std::string &filename); ///< See FLAC__stream_encoder_init_file()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(FILE *file); ///< See FLAC__stream_encoder_init_ogg_FILE()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(const char *filename); ///< See FLAC__stream_encoder_init_ogg_file()
virtual ::FLAC__StreamEncoderInitStatus init_ogg(const std::string &filename); ///< See FLAC__stream_encoder_init_ogg_file()
protected:
/// See FLAC__StreamEncoderProgressCallback
virtual void progress_callback(FLAC__uint64 bytes_written, FLAC__uint64 samples_written, unsigned frames_written, unsigned total_frames_estimate);
......@@ -282,8 +276,6 @@ namespace FLAC {
void operator=(const Stream &);
};
/* \} */
}
}
......
include/FLAC/export.h
View file @ 8da98c89
......@@ -52,4 +52,7 @@
#define FLAC_API_VERSION_REVISION 0
#define FLAC_API_VERSION_AGE 0
/** \c 1 if the library has been compiled with support for Ogg FLAC, else \c 0. */
extern int FLAC_API_SUPPORTS_OGG_FLAC;
#endif
include/FLAC/stream_decoder.h
View file @ 8da98c89
......@@ -208,6 +208,9 @@ typedef enum {
FLAC__STREAM_DECODER_END_OF_STREAM,
/**< The decoder has reached the end of the stream. */
FLAC__STREAM_DECODER_OGG_ERROR,
/**< An error occurred in the underlying Ogg layer. */
FLAC__STREAM_DECODER_SEEK_ERROR,
/**< An error occurred while seeking. The decoder must be flushed
* with FLAC__stream_decoder_flush() or reset with
......@@ -245,6 +248,11 @@ typedef enum {
FLAC__STREAM_DECODER_INIT_STATUS_OK = 0,
/**< Initialization was successful. */
FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER,
/**< The library was not compiled with support for the given container
* format.
*/
FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS,
/**< A required callback was not supplied. */
......@@ -659,6 +667,21 @@ FLAC_API void FLAC__stream_decoder_delete(FLAC__StreamDecoder *decoder);
*
***********************************************************************/
/** 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.
*/
FLAC_API FLAC__bool FLAC__stream_decoder_set_serial_number(FLAC__StreamDecoder *decoder, long serial_number);
/** 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
......@@ -875,24 +898,28 @@ FLAC_API unsigned FLAC__stream_decoder_get_blocksize(const FLAC__StreamDecoder *
* there may still be undecoded bytes in the decoder's read FIFO.
* The returned position is correct even after a seek.
*
* \warning This function currently only works for native FLAC,
* not Ogg FLAC streams.
*
* \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 true if successful, \c false if the stream is not native FLAC,
* or 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.
/** Initialize the decoder instance to decode native FLAC streams.
*
* 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 flavor of initialization sets up the decoder to decode from a
* native FLAC 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
......@@ -963,10 +990,91 @@ FLAC_API FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream(
void *client_data
);
/** Initialize the decoder instance.
/** Initialize the decoder instance to decode Ogg FLAC streams.
*
* This flavor of initialization sets up the decoder to decode from a plain
* file. For non-stdio streams, you must use
* This flavor of initialization sets up the decoder to decode from a
* FLAC stream in an Ogg container. I/O is performed via callbacks to the
* client. For decoding from a plain file via filename or open FILE*,
* FLAC__stream_decoder_init_ogg_file() and FLAC__stream_decoder_init_ogg_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.
*
* \note Support for Ogg FLAC in the library is optional. If this
* library has been built without support for Ogg FLAC, this function
* will return \c FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
*
* \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