Commit ec5ea04c authored by Josh Coalson's avatar Josh Coalson
Browse files

more comments

parent cb9d93ad
......@@ -100,16 +100,16 @@ extern "C" {
* metadata as well as an array of pointers (one for each channel)
* pointing to the decoded audio.
* - Metadata callback - This function will be called when the decoder has
* decoded a metadata block. There will always be one STREAMINFO block
* per stream, followed by zero or more other metadata blocks. These will
* be supplied by the decoder in the same order as they appear in the
* stream and always before the first audio frame (i.e. write callback).
* The metadata block that is passed in must not be modified, and it
* doesn't live beyond the callback, so you should make a copy of it with
* 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
* 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.
......@@ -442,8 +442,8 @@ FLAC__bool FLAC__stream_decoder_set_read_callback(FLAC__StreamDecoder *decoder,
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. There will always be one STREAMINFO block per stream,
* 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
......
......@@ -227,7 +227,11 @@ typedef enum {
/**< 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. */
/**< 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
* - 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_FATAL_ERROR_WHILE_ENCODING,
/**< An error occurred while writing the stream; usually, the write_callback returned an error. */
......@@ -616,8 +620,22 @@ FLAC__bool FLAC__stream_encoder_set_total_samples_estimate(FLAC__StreamEncoder *
* Otherwise, the encoder will not modify or free the blocks. It is up
* to the caller to free the metadata blocks after encoding.
*
* The STREAMINFO block is always written and no STREAMINFO block may
* occur in the supplied array.
* \note
* The encoder stores only the \a metadata pointer; the passed-in array
* must survive at least until after FLAC__stream_encoder_init() returns.
* Do not modify the array or free the blocks until then.
*
* \note
* The STREAMINFO block is always written and no STREAMINFO block may
* occur in the supplied array.
*
* \note
* A VORBIS_COMMENT block may be supplied. The vendor string in it
* will be ignored. libFLAC will use it's own vendor string. libFLAC
* will not modify the passed-in VORBIS_COMMENT's vendor string, it
* will simply write it's own into the stream. If no VORBIS_COMMENT
* block is present in the \a metadata array, libFLAC will write an
* empty one, containing only the vendor string.
*
* \default \c NULL, 0
* \param encoder An encoder instance to set.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment