*
* Second, there are two stream decoder classes. FLAC::Decoder::Stream
* is used for the same cases that FLAC__stream_decoder_init_stream() /
- * FLAC__stream_decoder_init_ogg_stream() is used, and FLAC::Decoder::File
+ * FLAC__stream_decoder_init_ogg_stream() are used, and FLAC::Decoder::File
* is used for the same cases that
* FLAC__stream_decoder_init_FILE() and FLAC__stream_decoder_init_file() /
* FLAC__stream_decoder_init_ogg_FILE() and FLAC__stream_decoder_init_ogg_file()
*
* Second, there are two stream encoder classes. FLAC::Encoder::Stream
* is used for the same cases that FLAC__stream_encoder_init_stream() /
- * FLAC__stream_encoder_init_ogg_stream() is used, and FLAC::Encoder::File
+ * FLAC__stream_encoder_init_ogg_stream() are used, and FLAC::Encoder::File
* is used for the same cases that
* FLAC__stream_encoder_init_FILE() and FLAC__stream_encoder_init_file() /
* FLAC__stream_encoder_init_ogg_FILE() and FLAC__stream_encoder_init_ogg_file()
*
* The behavior closely mimics the C layer interface; be sure to read
* the detailed description of the
- * \link flac_metadata C metadata module \endlink. Note that the
- * metadata API currently does not support Ogg FLAC files.
+ * \link flac_metadata C metadata module \endlink. Note that like the
+ * C layer, currently only the Chain interface (level 2) supports Ogg
+ * FLAC files, and it is read-only i.e. no writing back changed
+ * metadata to file.
*/
* global variables and should be thread-safe.
*
* libFLAC also supports encoding to and decoding from Ogg FLAC.
- * However the metadata editing interfaces currently work only for
- * native FLAC files.
+ * However the metadata editing interfaces currently have limited
+ * read-only support for Ogg FLAC files.
*
* \section cpp_api FLAC C++ API
*
* for the C++ API will be installed in your include area (for
* example /usr/include/FLAC++/...).
*
- * libFLAC++ also supports encoding to and decoding from Ogg FLAC.
- * However the metadata editing interfaces currently work only for
- * native FLAC files.
- *
* libFLAC++ is also licensed under
* <A HREF="../license.html">Xiph's BSD license</A>.
*
* - The decoder is independent of the encoder. The encoder uses the
* decoder because of the verify feature, but this can be removed if
* not needed.
- * - The metadata interface requires the stream decoder.
+ * - Parts of the metadata interface require the stream decoder (but not
+ * the encoder).
* - Ogg support is selectable through the compile time macro
* \c FLAC__HAS_OGG.
*
*
* 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
+ * FLAC__StreamDecoder. The old layers are now 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
* 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:
+ * add a call to this function if the default is not suitable. There
+ * are also two new convenience functions that may be useful:
* FLAC__metadata_object_cuesheet_calculate_cddb_id() and
* FLAC__metadata_get_cuesheet().
*
* \ingroup flac
*
* \brief
- * This module contains structure definitions for the representation
- * of FLAC format components in memory. These are the basic
- * structures used by the rest of the interfaces.
+ * This module contains #defines and symbols for exporting function
+ * calls, and providing version information and compiled-in features.
*
* \{
*/
*
* All levels access files via their filenames. In addition, level 2
* has additional alternative read and write functions that take an I/O
- * handle and callbacks, for times when access by filename is not possible.
+ * handle and callbacks, for situations where access by filename is not
+ * possible.
*
* In addition to the three interfaces, this module defines functions for
* creating and manipulating various metadata objects in memory. As we see
* \link flac_stream_decoder stream decoder \endlink module.
*/
-/** \defgroup flac_decoder FLAC/ *_decoder.h: decoder interfaces
+/** \defgroup flac_decoder FLAC/ \*_decoder.h: decoder interfaces
* \ingroup flac
*
* \brief
* 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
+ * or FLAC__stream_decoder_init_file(). Then you must only supply an open
+ * \c FILE* or filename and fewer callbacks; the decoder will handle
* the other callbacks internally.
*
* There are three similarly-named init functions for decoding from Ogg
* explicitly which blocks to parse and return via the metadata_callback
* and/or which to skip. Use a FLAC__stream_decoder_set_metadata_respond_all(),
* FLAC__stream_decoder_set_metadata_ignore() ... or FLAC__stream_decoder_set_metadata_ignore_all(),
- * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify which
- * blocks to return. Remember that some metadata blocks can be big so
- * filtering out the ones you don't use can reduce the memory requirements
- * of the decoder. Also note the special forms
- * FLAC__stream_decoder_set_metadata_respond_application(id) and
- * FLAC__stream_decoder_set_metadata_ignore_application(id) for filtering APPLICATION
- * blocks based on the application ID.
+ * FLAC__stream_decoder_set_metadata_respond() ... sequence to exactly specify
+ * which blocks to return. Remember that metadata blocks can potentially
+ * be big (for example, cover art) so filtering out the ones you don't
+ * use can reduce the memory requirements of the decoder. Also note the
+ * special forms FLAC__stream_decoder_set_metadata_respond_application(id)
+ * and FLAC__stream_decoder_set_metadata_ignore_application(id) for
+ * filtering APPLICATION blocks based on the application ID.
*
* STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but
* they still can legally be filtered from the metadata_callback.
* \link flac_stream_encoder stream encoder \endlink module.
*/
-/** \defgroup flac_encoder FLAC/ *_encoder.h: encoder interfaces
+/** \defgroup flac_encoder FLAC/ \*_encoder.h: encoder interfaces
* \ingroup flac
*
* \brief
* 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. Note that for Ogg FLAC
- * encoding you will usually get twice the number of callbacks than with
- * native FLAC, one for the Ogg page header and one for the page body.
+ * encoding you will usually get at least twice the number of callbacks than
+ * with native FLAC, one for the Ogg page header and one for the page body.
*
* After initializing the instance, the client may feed audio data to the
* encoder in one of two ways:
projects / platform / upstream / flac.git / commitdiff