/* libFLAC - Free Lossless Audio Codec library
- * Copyright (C) 2000,2001,2002,2003,2004 Josh Coalson
+ * 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
FLAC__STREAM_DECODER_ABORTED,
/**< The decoder was aborted by the read callback. */
- FLAC__STREAM_DECODER_UNPARSEABLE_STREAM,
- /**< The decoder encountered reserved fields in use in the stream. */
-
FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR,
/**< An error occurred allocating memory. */
extern FLAC_API const char * const FLAC__StreamDecoderWriteStatusString[];
-/** Possible values passed in to the FLAC__StreamDecoder error callback.
+/** Possible values passed back to the FLAC__StreamDecoder error callback.
+ * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
+ * all. The rest could be caused by bad sync (false synchronization on
+ * data that is not the start of a frame) or corrupted data. The error
+ * itself is the decoder's best guess at what happened assuming a correct
+ * sync. For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
+ * could be caused by a correct sync on the start of a frame, but some
+ * data in the frame header was corrupted. Or it could be the result of
+ * syncing on a point the stream that looked like the starting of a frame
+ * but was not. \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
+ * could be because the decoder encountered a valid frame made by a future
+ * version of the encoder which it cannot parse, or because of a false
+ * sync making it appear as though an encountered frame was generated by
+ * a future encoder.
*/
typedef enum {
FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER,
/**< The decoder encountered a corrupted frame header. */
- FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH
+ FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH,
/**< The frame's data did not match the CRC in the footer. */
+ FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
+ /**< The decoder encountered reserved fields in use in the stream. */
+
} FLAC__StreamDecoderErrorStatus;
/** Maps a FLAC__StreamDecoderErrorStatus to a C string.
*
* As the decoder needs more input it will call the read callback.
* Depending on what was decoded, the metadata or write callback will be
- * called with the decoded metadata block or audio frame, unless an error
- * occurred. If the decoder loses sync it will call the error callback
- * instead.
- *
- * \param decoder An initialized decoder instance in the state
- * \c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC.
+ * called with the decoded metadata block or audio frame.
+ *
+ * Unless there is a fatal read error or end of stream, this function
+ * will return once one whole frame is decoded. In other words, if the
+ * stream is not synchronized or points to a corrupt frame header, the
+ * decoder will continue to try and resync until it gets to a valid
+ * frame, then decode one frame, then return. If the decoder points to
+ * a frame whose frame CRC in the frame footer does not match the
+ * computed frame CRC, this function will issue a
+ * FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH error to the
+ * error callback, and return, having decoded one complete, although
+ * corrupt, frame. (Such corrupted frames are sent as silence of the
+ * correct length to the write callback.)
+ *
+ * \param decoder An initialized decoder instance.
* \assert
* \code decoder != NULL \endcode
- * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC \endcode
* \retval FLAC__bool
- * \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
- * in any case, check the decoder state with
- * FLAC__stream_decoder_get_state() to see what went wrong or to
- * check for lost synchronization (a sign of stream corruption).
+ * \c false if any fatal read, write, or memory allocation error
+ * occurred (meaning decoding must stop), else \c true; for more
+ * information about the decoder, check the decoder state with
+ * FLAC__stream_decoder_get_state().
*/
FLAC_API FLAC__bool FLAC__stream_decoder_process_single(FLAC__StreamDecoder *decoder);
*
* As the decoder needs more input it will call the read callback.
* As each metadata block is decoded, the metadata callback will be called
- * with the decoded metadata. If the decoder loses sync it will call the
- * error callback.
+ * with the decoded metadata.
*
- * \param decoder An initialized decoder instance in the state
- * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
+ * \param decoder An initialized decoder instance.
* \assert
* \code decoder != NULL \endcode
- * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
* \retval FLAC__bool
- * \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
- * in any case, check the decoder state with
- * FLAC__stream_decoder_get_state() to see what went wrong or to
- * check for lost synchronization (a sign of stream corruption).
+ * \c false if any fatal read, write, or memory allocation error
+ * occurred (meaning decoding must stop), else \c true; for more
+ * information about the decoder, check the decoder state with
+ * FLAC__stream_decoder_get_state().
*/
FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata(FLAC__StreamDecoder *decoder);
*
* As the decoder needs more input it will call the read callback.
* As each metadata block and frame is decoded, the metadata or write
- * callback will be called with the decoded metadata or frame. If the
- * decoder loses sync it will call the error callback.
+ * callback will be called with the decoded metadata or frame.
*
- * \param decoder An initialized decoder instance in the state
- * \c FLAC__STREAM_DECODER_SEARCH_FOR_METADATA.
+ * \param decoder An initialized decoder instance.
* \assert
* \code decoder != NULL \endcode
- * \code FLAC__stream_decoder_get_state(decoder) == FLAC__STREAM_DECODER_SEARCH_FOR_METADATA \endcode
* \retval FLAC__bool
- * \c false if any read or write error occurred (except
- * \c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC), else \c true;
- * in any case, check the decoder state with
- * FLAC__stream_decoder_get_state() to see what went wrong or to
- * check for lost synchronization (a sign of stream corruption).
+ * \c false if any fatal read, write, or memory allocation error
+ * occurred (meaning decoding must stop), else \c true; for more
+ * information about the decoder, check the decoder state with
+ * FLAC__stream_decoder_get_state().
*/
FLAC_API FLAC__bool FLAC__stream_decoder_process_until_end_of_stream(FLAC__StreamDecoder *decoder);
+/** Skip one audio frame.
+ * This version instructs the decoder to 'skip' a single frame and stop,
+ * unless the callbacks return a fatal error or the read callback returns
+ * \c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
+ *
+ * The decoding flow is the same as what occurs when
+ * FLAC__stream_decoder_process_single() is called to process an audio
+ * frame, except that this function does not decode the parsed data into
+ * PCM or call the write callback. The integrity of the frame is still
+ * checked the same way as in the other process functions.
+ *
+ * This function will return once one whole frame is skipped, in the
+ * same way that FLAC__stream_decoder_process_single() will return once
+ * one whole frame is decoded.
+ *
+ * This function, when used from the higher FLAC__SeekableStreamDecoder
+ * layer, can be used in more quickly determining FLAC frame boundaries
+ * when decoding of the actual data is not needed, for example when an
+ * application is separating a FLAC stream into frames for editing or
+ * storing in a container. To do this, the application can use
+ * FLAC__seekable_stream_decoder_skip_single_frame() to quickly advance
+ * to the next frame, then use
+ * FLAC__seekable_stream_decoder_get_decode_position() to find the new
+ * frame boundary.
+ *
+ * This function should only be called when the stream has advanced
+ * past all the metadata, otherwise it will return \c false.
+ *
+ * \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 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
+ * FLAC__stream_decoder_get_state().
+ */
+FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_frame(FLAC__StreamDecoder *decoder);
+
/* \} */
#ifdef __cplusplus
projects / platform / upstream / flac.git / blobdiff