cannam@86: cannam@86: cannam@86: FLAC: FLAC/stream_decoder.h: stream decoder interface cannam@86: cannam@86: cannam@86: cannam@86:
Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members
cannam@86:

FLAC/stream_decoder.h: stream decoder interface
cannam@86: cannam@86: [FLAC/_decoder.h: decoder interfaces] cannam@86:

Detailed Description

cannam@86: This module contains the functions which implement the stream decoder. cannam@86:

cannam@86: The stream decoder can decode native FLAC, and optionally Ogg FLAC (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.

cannam@86: The basic usage of this decoder is as follows:

cannam@86:

cannam@86: In more detail, the program will create a new instance by calling FLAC__stream_decoder_new(), then call FLAC__stream_decoder_set_*() functions to override the default decoder options, and call one of the FLAC__stream_decoder_init_*() functions.

cannam@86: There are three initialization functions for native FLAC, one for setting up the decoder to decode FLAC data from the client via callbacks, and two for decoding directly from a FLAC file.

cannam@86: For decoding via callbacks, use FLAC__stream_decoder_init_stream(). You must also supply several callbacks for handling I/O. Some (like seeking) are optional, depending on the capabilities of the input.

cannam@86: For decoding directly from a file, use FLAC__stream_decoder_init_FILE() or FLAC__stream_decoder_init_file(). Then you must only supply an open FILE* or filename and fewer callbacks; the decoder will handle the other callbacks internally.

cannam@86: There are three similarly-named init functions for decoding from Ogg FLAC streams. Check FLAC_API_SUPPORTS_OGG_FLAC to find out if the library has been built with Ogg support.

cannam@86: Once the decoder is initialized, your program will call one of several functions to start the decoding process:

cannam@86:

cannam@86:

cannam@86: When the decoder has finished decoding (normally or through an abort), the instance is finished by calling FLAC__stream_decoder_finish(), which ensures the decoder is in the correct state and frees memory. Then the instance may be deleted with FLAC__stream_decoder_delete() or initialized again to decode another stream.

cannam@86: Seeking is exposed through the FLAC__stream_decoder_seek_absolute() method. At any point after the stream decoder has been initialized, the client can call this function to seek to an exact sample within the stream. Subsequently, the first time the write callback is called it will be passed a (possibly partial) block starting at that sample.

cannam@86: If the client cannot seek via the callback interface provided, but still has another way of seeking, it can flush the decoder using FLAC__stream_decoder_flush() and start feeding data from the new position through the read callback.

cannam@86: The stream decoder also provides MD5 signature checking. If this is turned on before initialization, FLAC__stream_decoder_finish() will report when the decoded MD5 signature does not match the one stored in the STREAMINFO block. MD5 checking is automatically turned off (until the next FLAC__stream_decoder_reset()) if there is no signature in the STREAMINFO block or when a seek is attempted.

cannam@86: The FLAC__stream_decoder_set_metadata_*() functions deserve special attention. By default, the decoder only calls the metadata_callback for the STREAMINFO block. These functions allow you to tell the decoder 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 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.

cannam@86: STREAMINFO and SEEKTABLE blocks are always parsed and used internally, but they still can legally be filtered from the metadata_callback.

cannam@86:

Note:
The "set" functions may only be called when the decoder is in the state FLAC__STREAM_DECODER_UNINITIALIZED, i.e. after FLAC__stream_decoder_new() or FLAC__stream_decoder_finish(), but before FLAC__stream_decoder_init_*(). If this is the case they will return true, otherwise false.

cannam@86: FLAC__stream_decoder_finish() resets all settings to the constructor defaults, including the callbacks.

cannam@86: cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:

Classes

struct  FLAC__StreamDecoder

Typedefs

typedef FLAC__StreamDecoderReadStatus(* FLAC__StreamDecoderReadCallback )(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
typedef FLAC__StreamDecoderSeekStatus(* FLAC__StreamDecoderSeekCallback )(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
typedef FLAC__StreamDecoderTellStatus(* FLAC__StreamDecoderTellCallback )(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
typedef FLAC__StreamDecoderLengthStatus(* FLAC__StreamDecoderLengthCallback )(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
typedef FLAC__bool(* FLAC__StreamDecoderEofCallback )(const FLAC__StreamDecoder *decoder, void *client_data)
typedef FLAC__StreamDecoderWriteStatus(* FLAC__StreamDecoderWriteCallback )(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
typedef void(* FLAC__StreamDecoderMetadataCallback )(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
typedef void(* FLAC__StreamDecoderErrorCallback )(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)

Enumerations

enum  FLAC__StreamDecoderState {
cannam@86:   FLAC__STREAM_DECODER_SEARCH_FOR_METADATA = 0, cannam@86: FLAC__STREAM_DECODER_READ_METADATA, cannam@86: FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC, cannam@86: FLAC__STREAM_DECODER_READ_FRAME, cannam@86:
cannam@86:   FLAC__STREAM_DECODER_END_OF_STREAM, cannam@86: FLAC__STREAM_DECODER_OGG_ERROR, cannam@86: FLAC__STREAM_DECODER_SEEK_ERROR, cannam@86: FLAC__STREAM_DECODER_ABORTED, cannam@86:
cannam@86:   FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR, cannam@86: FLAC__STREAM_DECODER_UNINITIALIZED cannam@86:
cannam@86: }
enum  FLAC__StreamDecoderInitStatus {
cannam@86:   FLAC__STREAM_DECODER_INIT_STATUS_OK = 0, cannam@86: FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER, cannam@86: FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS, cannam@86: FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR, cannam@86:
cannam@86:   FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE, cannam@86: FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED cannam@86:
cannam@86: }
enum  FLAC__StreamDecoderReadStatus { FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, cannam@86: FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM, cannam@86: FLAC__STREAM_DECODER_READ_STATUS_ABORT cannam@86: }
enum  FLAC__StreamDecoderSeekStatus { FLAC__STREAM_DECODER_SEEK_STATUS_OK, cannam@86: FLAC__STREAM_DECODER_SEEK_STATUS_ERROR, cannam@86: FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED cannam@86: }
enum  FLAC__StreamDecoderTellStatus { FLAC__STREAM_DECODER_TELL_STATUS_OK, cannam@86: FLAC__STREAM_DECODER_TELL_STATUS_ERROR, cannam@86: FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED cannam@86: }
enum  FLAC__StreamDecoderLengthStatus { FLAC__STREAM_DECODER_LENGTH_STATUS_OK, cannam@86: FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR, cannam@86: FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED cannam@86: }
enum  FLAC__StreamDecoderWriteStatus { FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE, cannam@86: FLAC__STREAM_DECODER_WRITE_STATUS_ABORT cannam@86: }
enum  FLAC__StreamDecoderErrorStatus { FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC, cannam@86: FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER, cannam@86: FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH, cannam@86: FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM cannam@86: }

Functions

FLAC__StreamDecoder * FLAC__stream_decoder_new (void)
void FLAC__stream_decoder_delete (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_set_ogg_serial_number (FLAC__StreamDecoder *decoder, long serial_number)
FLAC__bool FLAC__stream_decoder_set_md5_checking (FLAC__StreamDecoder *decoder, FLAC__bool value)
FLAC__bool FLAC__stream_decoder_set_metadata_respond (FLAC__StreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool FLAC__stream_decoder_set_metadata_respond_application (FLAC__StreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool FLAC__stream_decoder_set_metadata_respond_all (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_set_metadata_ignore (FLAC__StreamDecoder *decoder, FLAC__MetadataType type)
FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application (FLAC__StreamDecoder *decoder, const FLAC__byte id[4])
FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all (FLAC__StreamDecoder *decoder)
FLAC__StreamDecoderState FLAC__stream_decoder_get_state (const FLAC__StreamDecoder *decoder)
const char * FLAC__stream_decoder_get_resolved_state_string (const FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_get_md5_checking (const FLAC__StreamDecoder *decoder)
FLAC__uint64 FLAC__stream_decoder_get_total_samples (const FLAC__StreamDecoder *decoder)
unsigned FLAC__stream_decoder_get_channels (const FLAC__StreamDecoder *decoder)
FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment (const FLAC__StreamDecoder *decoder)
unsigned FLAC__stream_decoder_get_bits_per_sample (const FLAC__StreamDecoder *decoder)
unsigned FLAC__stream_decoder_get_sample_rate (const FLAC__StreamDecoder *decoder)
unsigned FLAC__stream_decoder_get_blocksize (const FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_get_decode_position (const FLAC__StreamDecoder *decoder, FLAC__uint64 *position)
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream (FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback read_callback, FLAC__StreamDecoderSeekCallback seek_callback, FLAC__StreamDecoderTellCallback tell_callback, FLAC__StreamDecoderLengthCallback length_callback, FLAC__StreamDecoderEofCallback eof_callback, FLAC__StreamDecoderWriteCallback write_callback, FLAC__StreamDecoderMetadataCallback metadata_callback, FLAC__StreamDecoderErrorCallback error_callback, void *client_data)
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream (FLAC__StreamDecoder *decoder, FLAC__StreamDecoderReadCallback read_callback, FLAC__StreamDecoderSeekCallback seek_callback, FLAC__StreamDecoderTellCallback tell_callback, FLAC__StreamDecoderLengthCallback length_callback, FLAC__StreamDecoderEofCallback eof_callback, FLAC__StreamDecoderWriteCallback write_callback, FLAC__StreamDecoderMetadataCallback metadata_callback, FLAC__StreamDecoderErrorCallback error_callback, void *client_data)
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE (FLAC__StreamDecoder *decoder, FILE *file, FLAC__StreamDecoderWriteCallback write_callback, FLAC__StreamDecoderMetadataCallback metadata_callback, FLAC__StreamDecoderErrorCallback error_callback, void *client_data)
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE (FLAC__StreamDecoder *decoder, FILE *file, FLAC__StreamDecoderWriteCallback write_callback, FLAC__StreamDecoderMetadataCallback metadata_callback, FLAC__StreamDecoderErrorCallback error_callback, void *client_data)
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file (FLAC__StreamDecoder *decoder, const char *filename, FLAC__StreamDecoderWriteCallback write_callback, FLAC__StreamDecoderMetadataCallback metadata_callback, FLAC__StreamDecoderErrorCallback error_callback, void *client_data)
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file (FLAC__StreamDecoder *decoder, const char *filename, FLAC__StreamDecoderWriteCallback write_callback, FLAC__StreamDecoderMetadataCallback metadata_callback, FLAC__StreamDecoderErrorCallback error_callback, void *client_data)
FLAC__bool FLAC__stream_decoder_finish (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_flush (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_reset (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_process_single (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_process_until_end_of_stream (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_skip_single_frame (FLAC__StreamDecoder *decoder)
FLAC__bool FLAC__stream_decoder_seek_absolute (FLAC__StreamDecoder *decoder, FLAC__uint64 sample)

Variables

const char *const FLAC__StreamDecoderStateString []
const char *const FLAC__StreamDecoderInitStatusString []
const char *const FLAC__StreamDecoderReadStatusString []
const char *const FLAC__StreamDecoderSeekStatusString []
const char *const FLAC__StreamDecoderTellStatusString []
const char *const FLAC__StreamDecoderLengthStatusString []
const char *const FLAC__StreamDecoderWriteStatusString []
const char *const FLAC__StreamDecoderErrorStatusString []
cannam@86:

Typedef Documentation

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef FLAC__StreamDecoderReadStatus(* FLAC__StreamDecoderReadCallback)(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the read callback.

cannam@86: A function pointer matching this signature must be passed to FLAC__stream_decoder_init*_stream(). The supplied function will be called when the decoder needs more input data. The address of the buffer to be filled is supplied, along with the number of bytes the buffer can hold. The callback may choose to supply less data and modify the byte count but must be careful not to overflow the buffer. The callback then returns a status code chosen from FLAC__StreamDecoderReadStatus.

cannam@86: Here is an example of a read callback for stdio streams: 

 FLAC__StreamDecoderReadStatus read_cb(const FLAC__StreamDecoder *decoder, FLAC__byte buffer[], size_t *bytes, void *client_data)
cannam@86:  {
cannam@86:    FILE *file = ((MyClientData*)client_data)->file;
cannam@86:    if(*bytes > 0) {
cannam@86:      *bytes = fread(buffer, sizeof(FLAC__byte), *bytes, file);
cannam@86:      if(ferror(file))
cannam@86:        return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
cannam@86:      else if(*bytes == 0)
cannam@86:        return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM;
cannam@86:      else
cannam@86:        return FLAC__STREAM_DECODER_READ_STATUS_CONTINUE;
cannam@86:    }
cannam@86:    else
cannam@86:      return FLAC__STREAM_DECODER_READ_STATUS_ABORT;
cannam@86:  }
cannam@86:

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
buffer A pointer to a location for the callee to store data to be decoded.
bytes A pointer to the size of the buffer. On entry to the callback, it contains the maximum number of bytes that may be stored in buffer. The callee must set it to the actual number of bytes stored (0 in case of error or end-of-stream) before returning.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderReadStatus The callee's return status. Note that the callback should return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM if and only if zero bytes were read and there is no more data to be read.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef FLAC__StreamDecoderSeekStatus(* FLAC__StreamDecoderSeekCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the seek callback.

cannam@86: A function pointer matching this signature may be passed to FLAC__stream_decoder_init*_stream(). The supplied function will be called when the decoder needs to seek the input stream. The decoder will pass the absolute byte offset to seek to, 0 meaning the beginning of the stream.

cannam@86: Here is an example of a seek callback for stdio streams: 

 FLAC__StreamDecoderSeekStatus seek_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 absolute_byte_offset, void *client_data)
cannam@86:  {
cannam@86:    FILE *file = ((MyClientData*)client_data)->file;
cannam@86:    if(file == stdin)
cannam@86:      return FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED;
cannam@86:    else if(fseeko(file, (off_t)absolute_byte_offset, SEEK_SET) < 0)
cannam@86:      return FLAC__STREAM_DECODER_SEEK_STATUS_ERROR;
cannam@86:    else
cannam@86:      return FLAC__STREAM_DECODER_SEEK_STATUS_OK;
cannam@86:  }
cannam@86:

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
absolute_byte_offset The offset from the beginning of the stream to seek to.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderSeekStatus The callee's return status.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef FLAC__StreamDecoderTellStatus(* FLAC__StreamDecoderTellCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the tell callback.

cannam@86: A function pointer matching this signature may be passed to FLAC__stream_decoder_init*_stream(). The supplied function will be called when the decoder wants to know the current position of the stream. The callback should return the byte offset from the beginning of the stream.

cannam@86: Here is an example of a tell callback for stdio streams: 

 FLAC__StreamDecoderTellStatus tell_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *absolute_byte_offset, void *client_data)
cannam@86:  {
cannam@86:    FILE *file = ((MyClientData*)client_data)->file;
cannam@86:    off_t pos;
cannam@86:    if(file == stdin)
cannam@86:      return FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED;
cannam@86:    else if((pos = ftello(file)) < 0)
cannam@86:      return FLAC__STREAM_DECODER_TELL_STATUS_ERROR;
cannam@86:    else {
cannam@86:      *absolute_byte_offset = (FLAC__uint64)pos;
cannam@86:      return FLAC__STREAM_DECODER_TELL_STATUS_OK;
cannam@86:    }
cannam@86:  }
cannam@86:

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
absolute_byte_offset A pointer to storage for the current offset from the beginning of the stream.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderTellStatus The callee's return status.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef FLAC__StreamDecoderLengthStatus(* FLAC__StreamDecoderLengthCallback)(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the length callback.

cannam@86: A function pointer matching this signature may be passed to FLAC__stream_decoder_init*_stream(). The supplied function will be called when the decoder wants to know the total length of the stream in bytes.

cannam@86: Here is an example of a length callback for stdio streams: 

 FLAC__StreamDecoderLengthStatus length_cb(const FLAC__StreamDecoder *decoder, FLAC__uint64 *stream_length, void *client_data)
cannam@86:  {
cannam@86:    FILE *file = ((MyClientData*)client_data)->file;
cannam@86:    struct stat filestats;
cannam@86: 
cannam@86:    if(file == stdin)
cannam@86:      return FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED;
cannam@86:    else if(fstat(fileno(file), &filestats) != 0)
cannam@86:      return FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR;
cannam@86:    else {
cannam@86:      *stream_length = (FLAC__uint64)filestats.st_size;
cannam@86:      return FLAC__STREAM_DECODER_LENGTH_STATUS_OK;
cannam@86:    }
cannam@86:  }
cannam@86:

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
stream_length A pointer to storage for the length of the stream in bytes.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderLengthStatus The callee's return status.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef FLAC__bool(* FLAC__StreamDecoderEofCallback)(const FLAC__StreamDecoder *decoder, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the EOF callback.

cannam@86: A function pointer matching this signature may be passed to FLAC__stream_decoder_init*_stream(). The supplied function will be called when the decoder needs to know if the end of the stream has been reached.

cannam@86: Here is an example of a EOF callback for stdio streams: FLAC__bool eof_cb(const FLAC__StreamDecoder *decoder, void *client_data) 

 {
cannam@86:    FILE *file = ((MyClientData*)client_data)->file;
cannam@86:    return feof(file)? true : false;
cannam@86:  }
cannam@86:

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool true if the currently at the end of the stream, else false.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef FLAC__StreamDecoderWriteStatus(* FLAC__StreamDecoderWriteCallback)(const FLAC__StreamDecoder *decoder, const FLAC__Frame *frame, const FLAC__int32 *const buffer[], void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the write callback.

cannam@86: A function pointer matching this signature must be passed to one of the FLAC__stream_decoder_init_*() functions. The supplied function will be called when the decoder has decoded a single audio frame. The decoder will pass the frame metadata as well as an array of pointers (one for each channel) pointing to the decoded audio.

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
frame The description of the decoded frame. See FLAC__Frame.
buffer An array of pointers to decoded channels of data. Each pointer will point to an array of signed samples of length frame->header.blocksize. Channels will be ordered according to the FLAC specification; see the documentation for the frame header.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderWriteStatus The callee's return status.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef void(* FLAC__StreamDecoderMetadataCallback)(const FLAC__StreamDecoder *decoder, const FLAC__StreamMetadata *metadata, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the metadata callback.

cannam@86: A function pointer matching this signature must be passed to one of the FLAC__stream_decoder_init_*() functions. 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 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.

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
metadata The decoded metadata block.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
typedef void(* FLAC__StreamDecoderErrorCallback)(const FLAC__StreamDecoder *decoder, FLAC__StreamDecoderErrorStatus status, void *client_data)
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Signature for the error callback.

cannam@86: A function pointer matching this signature must be passed to one of the FLAC__stream_decoder_init_*() functions. The supplied function will be called whenever an error occurs during decoding.

cannam@86:

Note:
In general, FLAC__StreamDecoder functions which change the state should not be called on the decoder while in the callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder The decoder instance calling the callback.
status The error encountered by the decoder.
client_data The callee's client data set through FLAC__stream_decoder_init_*().
cannam@86:
cannam@86:
cannam@86:

Enumeration Type Documentation

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderState
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: State values for a FLAC__StreamDecoder

cannam@86: The decoder's state can be obtained by calling FLAC__stream_decoder_get_state().

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_SEARCH_FOR_METADATA  cannam@86: The decoder is ready to search for metadata.
FLAC__STREAM_DECODER_READ_METADATA  cannam@86: The decoder is ready to or is in the process of reading metadata.
FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC  cannam@86: The decoder is ready to or is in the process of searching for the frame sync code.
FLAC__STREAM_DECODER_READ_FRAME  cannam@86: The decoder is ready to or is in the process of reading a frame.
FLAC__STREAM_DECODER_END_OF_STREAM  cannam@86: The decoder has reached the end of the stream.
FLAC__STREAM_DECODER_OGG_ERROR  cannam@86: An error occurred in the underlying Ogg layer.
FLAC__STREAM_DECODER_SEEK_ERROR  cannam@86: An error occurred while seeking. The decoder must be flushed with FLAC__stream_decoder_flush() or reset with FLAC__stream_decoder_reset() before decoding can continue.
FLAC__STREAM_DECODER_ABORTED  cannam@86: The decoder was aborted by the read callback.
FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR  cannam@86: An error occurred allocating memory. The decoder is in an invalid state and can no longer be used.
FLAC__STREAM_DECODER_UNINITIALIZED  cannam@86: The decoder is in the uninitialized state; one of the FLAC__stream_decoder_init_*() functions must be called before samples can be processed.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderInitStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Possible return values for the FLAC__stream_decoder_init_*() functions.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_INIT_STATUS_OK  cannam@86: Initialization was successful.
FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER  cannam@86: The library was not compiled with support for the given container format.
FLAC__STREAM_DECODER_INIT_STATUS_INVALID_CALLBACKS  cannam@86: A required callback was not supplied.
FLAC__STREAM_DECODER_INIT_STATUS_MEMORY_ALLOCATION_ERROR  cannam@86: An error occurred allocating memory.
FLAC__STREAM_DECODER_INIT_STATUS_ERROR_OPENING_FILE  cannam@86: fopen() failed in FLAC__stream_decoder_init_file() or FLAC__stream_decoder_init_ogg_file().
FLAC__STREAM_DECODER_INIT_STATUS_ALREADY_INITIALIZED  cannam@86: FLAC__stream_decoder_init_*() was called when the decoder was already initialized, usually because FLAC__stream_decoder_finish() was not called.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderReadStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Return values for the FLAC__StreamDecoder read callback.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_READ_STATUS_CONTINUE  cannam@86: The read was OK and decoding can continue.
FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM  cannam@86: The read was attempted while at the end of the stream. Note that the client must only return this value when the read callback was called when already at the end of the stream. Otherwise, if the read itself moves to the end of the stream, the client should still return the data and FLAC__STREAM_DECODER_READ_STATUS_CONTINUE, and then on the next read callback it should return FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM with a byte count of 0.
FLAC__STREAM_DECODER_READ_STATUS_ABORT  cannam@86: An unrecoverable error occurred. The decoder will return from the process call.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderSeekStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Return values for the FLAC__StreamDecoder seek callback.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_SEEK_STATUS_OK  cannam@86: The seek was OK and decoding can continue.
FLAC__STREAM_DECODER_SEEK_STATUS_ERROR  cannam@86: An unrecoverable error occurred. The decoder will return from the process call.
FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED  cannam@86: Client does not support seeking.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderTellStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Return values for the FLAC__StreamDecoder tell callback.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_TELL_STATUS_OK  cannam@86: The tell was OK and decoding can continue.
FLAC__STREAM_DECODER_TELL_STATUS_ERROR  cannam@86: An unrecoverable error occurred. The decoder will return from the process call.
FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED  cannam@86: Client does not support telling the position.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderLengthStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Return values for the FLAC__StreamDecoder length callback.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_LENGTH_STATUS_OK  cannam@86: The length call was OK and decoding can continue.
FLAC__STREAM_DECODER_LENGTH_STATUS_ERROR  cannam@86: An unrecoverable error occurred. The decoder will return from the process call.
FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED  cannam@86: Client does not support reporting the length.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderWriteStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Return values for the FLAC__StreamDecoder write callback.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_WRITE_STATUS_CONTINUE  cannam@86: The write was OK and decoding can continue.
FLAC__STREAM_DECODER_WRITE_STATUS_ABORT  cannam@86: An unrecoverable error occurred. The decoder will return from the process call.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
enum FLAC__StreamDecoderErrorStatus
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Possible values passed back to the FLAC__StreamDecoder error callback. 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 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. 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.

Enumeration values:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC  cannam@86: An error in the stream caused the decoder to lose synchronization.
FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER  cannam@86: The decoder encountered a corrupted frame header.
FLAC__STREAM_DECODER_ERROR_STATUS_FRAME_CRC_MISMATCH  cannam@86: The frame's data did not match the CRC in the footer.
FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM  cannam@86: The decoder encountered reserved fields in use in the stream.
cannam@86:
cannam@86:
cannam@86:

Function Documentation

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoder* FLAC__stream_decoder_new ( void   ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Create a new stream decoder instance. The instance is created with default settings; see the individual FLAC__stream_decoder_set_*() functions for each setting's default.

cannam@86:

Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoder* NULL if there was an error allocating memory, else the new instance.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
void FLAC__stream_decoder_delete ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Free a decoder instance. Deletes the object pointed to by decoder.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A pointer to an existing decoder.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_ogg_serial_number ( FLAC__StreamDecoder *  decoder,
long  serial_number
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Set the serial number for the FLAC stream within the Ogg container. 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.

cannam@86:

Note:
This does not need to be set for native FLAC decoding.
cannam@86:
Default Value:
use serial number of first page
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
serial_number See above.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_md5_checking ( FLAC__StreamDecoder *  decoder,
FLAC__bool  value
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Set the "MD5 signature checking" flag. If 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 exists, during FLAC__stream_decoder_finish().

cannam@86: MD5 signature checking will be turned off (until the next FLAC__stream_decoder_reset()) if there is no signature in the STREAMINFO block or when a seek is attempted.

cannam@86: Clients that do not use the MD5 check should leave this off to speed up decoding.

cannam@86:

Default Value:
false
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
value Flag value (see above).
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_metadata_respond ( FLAC__StreamDecoder *  decoder,
FLAC__MetadataType  type
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Direct the decoder to pass on all metadata blocks of type type.

cannam@86:

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
type See above.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
type is valid
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_metadata_respond_application ( FLAC__StreamDecoder *  decoder,
const FLAC__byte  id[4]
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Direct the decoder to pass on all APPLICATION metadata blocks of the given id.

cannam@86:

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
id See above.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86: 
 id != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_metadata_respond_all ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Direct the decoder to pass on all metadata blocks of any type.

cannam@86:

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_metadata_ignore ( FLAC__StreamDecoder *  decoder,
FLAC__MetadataType  type
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Direct the decoder to filter out all metadata blocks of type type.

cannam@86:

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
type See above.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
type is valid
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_metadata_ignore_application ( FLAC__StreamDecoder *  decoder,
const FLAC__byte  id[4]
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Direct the decoder to filter out all APPLICATION metadata blocks of the given id.

cannam@86:

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
id See above.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86: 
 id != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_set_metadata_ignore_all ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Direct the decoder to filter out all metadata blocks of any type.

cannam@86:

Default Value:
By default, only the STREAMINFO block is returned via the metadata callback.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to set.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if the decoder is already initialized, else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderState FLAC__stream_decoder_get_state ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current decoder state.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderState The current decoder state.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* FLAC__stream_decoder_get_resolved_state_string ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current decoder state as a C string.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
const char * The decoder state as a C string. Do not modify the contents.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_get_md5_checking ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the "MD5 signature checking" flag. This is the value of the setting, not whether or not the decoder is currently checking the MD5 (remember, it can be turned off automatically by a seek). When the decoder is reset the flag will be restored to the value returned by this function.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__uint64 FLAC__stream_decoder_get_total_samples ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the total number of samples in the stream being decoded. Will only be valid after decoding has started and will contain the value from the STREAMINFO block. A value of 0 means "unknown".

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
unsigned See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
unsigned FLAC__stream_decoder_get_channels ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current number of channels in the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
unsigned See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__ChannelAssignment FLAC__stream_decoder_get_channel_assignment ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current channel assignment in the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__ChannelAssignment See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
unsigned FLAC__stream_decoder_get_bits_per_sample ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current sample resolution in the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
unsigned See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
unsigned FLAC__stream_decoder_get_sample_rate ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current sample rate in Hz of the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
unsigned See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
unsigned FLAC__stream_decoder_get_blocksize ( const FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Get the current blocksize of the stream being decoded. Will only be valid after decoding has started and will contain the value from the most recently decoded frame header.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
unsigned See above.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_get_decode_position ( const FLAC__StreamDecoder *  decoder,
FLAC__uint64 *  position
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Returns the decoder's current read position within the stream. The position is the byte offset from the start of the stream. Bytes before this position have been fully decoded. Note that there may still be undecoded bytes in the decoder's read FIFO. The returned position is correct even after a seek.

cannam@86:

Warning:
This function currently only works for native FLAC, not Ogg FLAC streams.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance to query.
position Address at which to return the desired position.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86: 
 position != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool true if successful, false if the stream is not native FLAC, or there was an error from the 'tell' callback or it returned FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_stream ( FLAC__StreamDecoder *  decoder,
FLAC__StreamDecoderReadCallback  read_callback,
FLAC__StreamDecoderSeekCallback  seek_callback,
FLAC__StreamDecoderTellCallback  tell_callback,
FLAC__StreamDecoderLengthCallback  length_callback,
FLAC__StreamDecoderEofCallback  eof_callback,
FLAC__StreamDecoderWriteCallback  write_callback,
FLAC__StreamDecoderMetadataCallback  metadata_callback,
FLAC__StreamDecoderErrorCallback  error_callback,
void *  client_data
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Initialize the decoder instance to decode native FLAC streams.

cannam@86: 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.

cannam@86: 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.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
read_callback See FLAC__StreamDecoderReadCallback. This pointer must not be NULL.
seek_callback See FLAC__StreamDecoderSeekCallback. This pointer may be NULL if seeking is not supported. If seek_callback is not NULL then a tell_callback, length_callback, and eof_callback must also be supplied. Alternatively, a dummy seek callback that just returns FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED may also be supplied, all though this is slightly less efficient for the decoder.
tell_callback See FLAC__StreamDecoderTellCallback. This pointer may be NULL if not supported by the client. If seek_callback is not NULL then a tell_callback must also be supplied. Alternatively, a dummy tell callback that just returns FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED may also be supplied, all though this is slightly less efficient for the decoder.
length_callback See FLAC__StreamDecoderLengthCallback. This pointer may be NULL if not supported by the client. If seek_callback is not NULL then a length_callback must also be supplied. Alternatively, a dummy length callback that just returns FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED may also be supplied, all though this is slightly less efficient for the decoder.
eof_callback See FLAC__StreamDecoderEofCallback. This pointer may be NULL if not supported by the client. If seek_callback is not NULL then a eof_callback must also be supplied. Alternatively, a dummy length callback that just returns false may also be supplied, all though this is slightly less efficient for the decoder.
write_callback See FLAC__StreamDecoderWriteCallback. This pointer must not be NULL.
metadata_callback See FLAC__StreamDecoderMetadataCallback. This pointer may be NULL if the callback is not desired.
error_callback See FLAC__StreamDecoderErrorCallback. This pointer must not be NULL.
client_data This value will be supplied to callbacks in their client_data argument.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_stream ( FLAC__StreamDecoder *  decoder,
FLAC__StreamDecoderReadCallback  read_callback,
FLAC__StreamDecoderSeekCallback  seek_callback,
FLAC__StreamDecoderTellCallback  tell_callback,
FLAC__StreamDecoderLengthCallback  length_callback,
FLAC__StreamDecoderEofCallback  eof_callback,
FLAC__StreamDecoderWriteCallback  write_callback,
FLAC__StreamDecoderMetadataCallback  metadata_callback,
FLAC__StreamDecoderErrorCallback  error_callback,
void *  client_data
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Initialize the decoder instance to decode Ogg FLAC streams.

cannam@86: 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.

cannam@86: 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.

cannam@86:

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 FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
read_callback See FLAC__StreamDecoderReadCallback. This pointer must not be NULL.
seek_callback See FLAC__StreamDecoderSeekCallback. This pointer may be NULL if seeking is not supported. If seek_callback is not NULL then a tell_callback, length_callback, and eof_callback must also be supplied. Alternatively, a dummy seek callback that just returns FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED may also be supplied, all though this is slightly less efficient for the decoder.
tell_callback See FLAC__StreamDecoderTellCallback. This pointer may be NULL if not supported by the client. If seek_callback is not NULL then a tell_callback must also be supplied. Alternatively, a dummy tell callback that just returns FLAC__STREAM_DECODER_TELL_STATUS_UNSUPPORTED may also be supplied, all though this is slightly less efficient for the decoder.
length_callback See FLAC__StreamDecoderLengthCallback. This pointer may be NULL if not supported by the client. If seek_callback is not NULL then a length_callback must also be supplied. Alternatively, a dummy length callback that just returns FLAC__STREAM_DECODER_LENGTH_STATUS_UNSUPPORTED may also be supplied, all though this is slightly less efficient for the decoder.
eof_callback See FLAC__StreamDecoderEofCallback. This pointer may be NULL if not supported by the client. If seek_callback is not NULL then a eof_callback must also be supplied. Alternatively, a dummy length callback that just returns false may also be supplied, all though this is slightly less efficient for the decoder.
write_callback See FLAC__StreamDecoderWriteCallback. This pointer must not be NULL.
metadata_callback See FLAC__StreamDecoderMetadataCallback. This pointer may be NULL if the callback is not desired.
error_callback See FLAC__StreamDecoderErrorCallback. This pointer must not be NULL.
client_data This value will be supplied to callbacks in their client_data argument.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_FILE ( FLAC__StreamDecoder *  decoder,
FILE *  file,
FLAC__StreamDecoderWriteCallback  write_callback,
FLAC__StreamDecoderMetadataCallback  metadata_callback,
FLAC__StreamDecoderErrorCallback  error_callback,
void *  client_data
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Initialize the decoder instance to decode native FLAC files.

cannam@86: This flavor of initialization sets up the decoder to decode from a plain native FLAC file. For non-stdio streams, you must use FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.

cannam@86: 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.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
file An open FLAC file. The file should have been opened with mode "rb" and rewound. The file becomes owned by the decoder and should not be manipulated by the client while decoding. Unless file is stdin, it will be closed when FLAC__stream_decoder_finish() is called. Note however that seeking will not work when decoding from stdout since it is not seekable.
write_callback See FLAC__StreamDecoderWriteCallback. This pointer must not be NULL.
metadata_callback See FLAC__StreamDecoderMetadataCallback. This pointer may be NULL if the callback is not desired.
error_callback See FLAC__StreamDecoderErrorCallback. This pointer must not be NULL.
client_data This value will be supplied to callbacks in their client_data argument.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86: 
 file != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_FILE ( FLAC__StreamDecoder *  decoder,
FILE *  file,
FLAC__StreamDecoderWriteCallback  write_callback,
FLAC__StreamDecoderMetadataCallback  metadata_callback,
FLAC__StreamDecoderErrorCallback  error_callback,
void *  client_data
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Initialize the decoder instance to decode Ogg FLAC files.

cannam@86: This flavor of initialization sets up the decoder to decode from a plain Ogg FLAC file. For non-stdio streams, you must use FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.

cannam@86: 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.

cannam@86:

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 FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
file An open FLAC file. The file should have been opened with mode "rb" and rewound. The file becomes owned by the decoder and should not be manipulated by the client while decoding. Unless file is stdin, it will be closed when FLAC__stream_decoder_finish() is called. Note however that seeking will not work when decoding from stdout since it is not seekable.
write_callback See FLAC__StreamDecoderWriteCallback. This pointer must not be NULL.
metadata_callback See FLAC__StreamDecoderMetadataCallback. This pointer may be NULL if the callback is not desired.
error_callback See FLAC__StreamDecoderErrorCallback. This pointer must not be NULL.
client_data This value will be supplied to callbacks in their client_data argument.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86: 
 file != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_file ( FLAC__StreamDecoder *  decoder,
const char *  filename,
FLAC__StreamDecoderWriteCallback  write_callback,
FLAC__StreamDecoderMetadataCallback  metadata_callback,
FLAC__StreamDecoderErrorCallback  error_callback,
void *  client_data
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Initialize the decoder instance to decode native FLAC files.

cannam@86: This flavor of initialization sets up the decoder to decode from a plain native FLAC file. If POSIX fopen() semantics are not sufficient, (for example, with Unicode filenames on Windows), you must use FLAC__stream_decoder_init_FILE(), or FLAC__stream_decoder_init_stream() and provide callbacks for the I/O.

cannam@86: 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.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
filename The name of the file to decode from. The file will be opened with fopen(). Use NULL to decode from stdin. Note that stdin is not seekable.
write_callback See FLAC__StreamDecoderWriteCallback. This pointer must not be NULL.
metadata_callback See FLAC__StreamDecoderMetadataCallback. This pointer may be NULL if the callback is not desired.
error_callback See FLAC__StreamDecoderErrorCallback. This pointer must not be NULL.
client_data This value will be supplied to callbacks in their client_data argument.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__stream_decoder_init_ogg_file ( FLAC__StreamDecoder *  decoder,
const char *  filename,
FLAC__StreamDecoderWriteCallback  write_callback,
FLAC__StreamDecoderMetadataCallback  metadata_callback,
FLAC__StreamDecoderErrorCallback  error_callback,
void *  client_data
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Initialize the decoder instance to decode Ogg FLAC files.

cannam@86: This flavor of initialization sets up the decoder to decode from a plain Ogg FLAC file. If POSIX fopen() semantics are not sufficient, (for example, with Unicode filenames on Windows), you must use FLAC__stream_decoder_init_ogg_FILE(), or FLAC__stream_decoder_init_ogg_stream() and provide callbacks for the I/O.

cannam@86: 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.

cannam@86:

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 FLAC__STREAM_DECODER_INIT_STATUS_UNSUPPORTED_CONTAINER.
cannam@86:
Parameters:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
filename The name of the file to decode from. The file will be opened with fopen(). Use NULL to decode from stdin. Note that stdin is not seekable.
write_callback See FLAC__StreamDecoderWriteCallback. This pointer must not be NULL.
metadata_callback See FLAC__StreamDecoderMetadataCallback. This pointer may be NULL if the callback is not desired.
error_callback See FLAC__StreamDecoderErrorCallback. This pointer must not be NULL.
client_data This value will be supplied to callbacks in their client_data argument.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__StreamDecoderInitStatus FLAC__STREAM_DECODER_INIT_STATUS_OK if initialization was successful; see FLAC__StreamDecoderInitStatus for the meanings of other return values.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_finish ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Finish the decoding process. Flushes the decoding buffer, releases resources, resets the decoder settings to their defaults, and returns the decoder state to FLAC__STREAM_DECODER_UNINITIALIZED.

cannam@86: In the event of a prematurely-terminated decode, it is not strictly necessary to call this immediately before FLAC__stream_decoder_delete() but it is good practice to match every FLAC__stream_decoder_init_*() with a FLAC__stream_decoder_finish().

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder An uninitialized decoder instance.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if MD5 checking is on AND a STREAMINFO block was available AND the MD5 signature in the STREAMINFO block was non-zero AND the signature does not match the one computed by the decoder; else true.
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_flush ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Flush the stream input. The decoder's input buffer will be cleared and the state set to FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. This will also turn off MD5 checking.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool true if successful, else false if a memory allocation error occurs (in which case the state will be set to FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR).
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_reset ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Reset the decoding process. The decoder's input buffer will be cleared and the state set to FLAC__STREAM_DECODER_SEARCH_FOR_METADATA. This is similar to FLAC__stream_decoder_finish() except that the settings are preserved; there is no need to call FLAC__stream_decoder_init_*() before decoding again. MD5 checking will be restored to its original setting.

cannam@86: If the decoder is seekable, or was initialized with FLAC__stream_decoder_init*_FILE() or FLAC__stream_decoder_init*_file(), the decoder will also attempt to seek to the beginning of the file. If this rewind fails, this function will return false. It follows that FLAC__stream_decoder_reset() cannot be used when decoding from stdin.

cannam@86: If the decoder was initialized with FLAC__stream_encoder_init*_stream() and is not seekable (i.e. no seek callback was provided or the seek callback returns FLAC__STREAM_DECODER_SEEK_STATUS_UNSUPPORTED), it is the duty of the client to start feeding data from the beginning of the stream on the next FLAC__stream_decoder_process() or FLAC__stream_decoder_process_interleaved() call.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder A decoder instance.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool true if successful, else false if a memory allocation occurs (in which case the state will be set to FLAC__STREAM_DECODER_MEMORY_ALLOCATION_ERROR) or a seek error occurs (the state will be unchanged).
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_process_single ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Decode one metadata block or audio frame. This version instructs the decoder to decode a either a single metadata block or a single frame and stop, unless the callbacks return a fatal error or the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.

cannam@86: 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.

cannam@86: 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.)

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder An initialized decoder instance.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if any fatal read, write, or memory allocation error occurred (meaning decoding must stop), else true; for more information about the decoder, check the decoder state with FLAC__stream_decoder_get_state().
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_process_until_end_of_metadata ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Decode until the end of the metadata. This version instructs the decoder to decode from the current position and continue until all the metadata has been read, or until the callbacks return a fatal error or the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.

cannam@86: 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.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder An initialized decoder instance.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if any fatal read, write, or memory allocation error occurred (meaning decoding must stop), else true; for more information about the decoder, check the decoder state with FLAC__stream_decoder_get_state().
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_process_until_end_of_stream ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Decode until the end of the stream. This version instructs the decoder to decode from the current position and continue until the end of stream (the read callback returns FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the callbacks return a fatal error.

cannam@86: 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.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder An initialized decoder instance.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool false if any fatal read, write, or memory allocation error occurred (meaning decoding must stop), else true; for more information about the decoder, check the decoder state with FLAC__stream_decoder_get_state().
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_skip_single_frame ( FLAC__StreamDecoder *  decoder  ) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: 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 FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.

cannam@86: 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.

cannam@86: 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.

cannam@86: This function 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__stream_decoder_skip_single_frame() to quickly advance to the next frame, then use FLAC__stream_decoder_get_decode_position() to find the new frame boundary.

cannam@86: This function should only be called when the stream has advanced past all the metadata, otherwise it will return false.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86:
decoder An initialized decoder instance not in a metadata state.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool 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 true; for more information about the decoder, check the decoder state with FLAC__stream_decoder_get_state().
cannam@86:
cannam@86:
cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
FLAC__bool FLAC__stream_decoder_seek_absolute ( FLAC__StreamDecoder *  decoder,
FLAC__uint64  sample
) 
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Flush the input and seek to an absolute sample. Decoding will resume at the given sample. Note that because of this, the next write callback may contain a partial block. The client must support seeking the input or this function will fail and return false. Furthermore, if the decoder state is FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed with FLAC__stream_decoder_flush() or reset with FLAC__stream_decoder_reset() before decoding can continue.

cannam@86:

Parameters:
cannam@86: cannam@86: cannam@86: cannam@86:
decoder A decoder instance.
sample The target sample number to seek to.
cannam@86:
cannam@86:
Assertions: 
 decoder != NULL 
cannam@86:
cannam@86:
Return values:
cannam@86: cannam@86: cannam@86:
FLAC__bool true if successful, else false.
cannam@86:
cannam@86:
cannam@86:

Variable Documentation

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderStateString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderState to a C string.

cannam@86: Using a FLAC__StreamDecoderState as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderInitStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderInitStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderInitStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderReadStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderReadStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderReadStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderSeekStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderSeekStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderSeekStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderTellStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderTellStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderTellStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderLengthStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderLengthStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderLengthStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderWriteStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderWriteStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderWriteStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86:

cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
const char* const FLAC__StreamDecoderErrorStatusString[]
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86:   cannam@86: cannam@86: cannam@86:

cannam@86: Maps a FLAC__StreamDecoderErrorStatus to a C string.

cannam@86: Using a FLAC__StreamDecoderErrorStatus as the index to this array will give the string equivalent. The contents should not be modified.

cannam@86: cannam@86:

cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86:
cannam@86: Copyright (c) 2000,2001,2002,2003,2004,2005,2006,2007 Josh Coalson cannam@86: cannam@86: SourceForge.net Logo cannam@86:
cannam@86:
cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: cannam@86: