A structure for holding a set of callbacks.
Each FLAC interface that requires a FLAC__IOCallbacks structure will
describe which of the callbacks are required. The ones that are not
required may be set to NULL.
The opaque structure definition for the stream decoder type.
See the \link flac_stream_decoder stream decoder module \endlink
for a detailed description.
The opaque structure definition for the stream encoder type.
See the \link flac_stream_encoder stream encoder module \endlink
for a detailed description.
Structure that is used when a metadata block of unknown type is loaded.
The contents are opaque. The structure is used only internally to
correctly handle unknown metadata.
Tests that a sample rate is valid for the FLAC subset. The subset rules
for valid sample rates are slightly more complex since the rate has to
be expressible completely in the frame header.
Sort a seek table’s seek points according to the format specification.
This includes a “unique-ification” step to remove duplicates, i.e.
seek points with identical \a sample_number values. Duplicate seek
points are converted into placeholder points and sorted to the end of
the table.
Get the current status of the chain. Call this after a function
returns \c false to get the reason for the error. Also resets the
status to FLAC__METADATA_CHAIN_STATUS_OK.
Write all metadata out to the FLAC file. This function tries to be as
efficient as possible; how the metadata is actually written is shown by
the following:
Read a PICTURE metadata block of the given FLAC file. This
function will try to skip any ID3v2 tag at the head of the file.
Since there can be more than one PICTURE block in a file, this
function takes a number of parameters that act as constraints to
the search. The PICTURE block with the largest area matching all
the constraints will be returned, or \a *picture will be set to
\c NULL if there was no such block.
Removes the current block from the chain. If \a replace_with_padding is
\c true, the block will instead be replaced with a padding block of equal
size. You can not delete the STREAMINFO block. The iterator will be
left pointing to the block before the one just “deleted”, even if
\a replace_with_padding is \c true.
Get the metadata block at the current position. You can modify
the block in place but must write the chain before the changes
are reflected to the FLAC file. You do not need to call
FLAC__metadata_iterator_set_block() to reflect the changes;
the pointer returned by FLAC__metadata_iterator_get_block()
points directly into the chain.
Insert a new block after the current block. You cannot insert a STREAMINFO
block as there can be only one, the one that already exists at the head when
you read in a chain. The chain takes ownership of the new block and it will
be deleted when the chain is deleted. The iterator will be left pointing to
the new block.
Insert a new block before the current block. You cannot insert a block
before the first STREAMINFO block. You cannot insert a STREAMINFO block
as there can be only one, the one that already exists at the head when you
read in a chain. The chain takes ownership of the new block and it will be
deleted when the chain is deleted. The iterator will be left pointing to
the new block.
Set the metadata block at the current position, replacing the existing
block. The new block passed in becomes owned by the chain and it will be
deleted when the chain is deleted.
Calculate and return the CDDB/freedb ID for a cue sheet. The function
assumes the cue sheet corresponds to a CD; the result is undefined
if the cuesheet’s is_cd bit is not set.
Deletes the block at the current position. This will cause the
entire FLAC file to be rewritten, unless \a use_padding is \c true,
in which case the block will be replaced by an equal-sized PADDING
block. The iterator will be left pointing to the block before the
one just deleted.
Get the application ID of the \c APPLICATION block at the current
position. This avoids reading the actual block data which can save
time for large blocks.
Get the metadata block at the current position. You can modify the
block but must use FLAC__metadata_simple_iterator_set_block() to
write it back to the FLAC file.
This is similar to FLAC__metadata_simple_iterator_set_block()
except that instead of writing over an existing block, it appends
a block after the existing block. \a use_padding is again used to
tell the function to try an expand into following padding in an
attempt to avoid rewriting the entire file.
Returns \c true if the FLAC file is writable. If \c false, calls to
FLAC__metadata_simple_iterator_set_block() and
FLAC__metadata_simple_iterator_insert_block_after() will fail.
Get the current status of the iterator. Call this after a function
returns \c false to get the reason for the error. Also resets the status
to FLAC__METADATA_SIMPLE_ITERATOR_STATUS_OK.
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.
Flush the stream input.
The decoder’s input buffer will be cleared and the state set to
\c FLAC__STREAM_DECODER_SEARCH_FOR_FRAME_SYNC. This will also turn
off MD5 checking.
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.
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.
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.
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.
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.
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.
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.
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 \c STREAMINFO block. A value of \c 0 means “unknown”.
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.
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
\c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
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
\c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
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
\c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM), or until the
callbacks return a fatal error.
Reset the decoding process.
The decoder’s input buffer will be cleared and the state set to
\c 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.
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 \c false. Furthermore, if the decoder state is
\c 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.
Set the “MD5 signature checking” flag. If \c true, the decoder will
compute the MD5 signature of the unencoded audio data while decoding
and compare it to the signature from the STREAMINFO block, if it
exists, during FLAC__stream_decoder_finish().
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.
Skip one audio frame.
This version instructs the decoder to ‘skip’ a single frame and stop,
unless the callbacks return a fatal error or the read callback returns
\c FLAC__STREAM_DECODER_READ_STATUS_END_OF_STREAM.
Finish the encoding process.
Flushes the encoding buffer, releases resources, resets the encoder
settings to their defaults, and returns the encoder state to
FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate
one or more write callbacks before returning, and will generate
a metadata callback.
Get the current encoder state as a C string.
This version automatically resolves
\c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the
verify decoder’s state.
Get the previously set estimate of the total samples to be encoded.
The encoder merely mimics back the value given to
FLAC__stream_encoder_set_total_samples_estimate() since it has no
other way of knowing how many samples the client will encode.
Get relevant values about the nature of a verify decoder error.
Useful when the stream encoder state is
\c FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should
be addresses in which the stats will be returned, or NULL if value
is not desired.
Create a new stream encoder instance. The instance is created with
default settings; see the individual FLAC__stream_encoder_set_*()
functions for each setting’s default.
Submit data for encoding.
This version allows you to supply the input data via an array of
pointers, each pointer pointing to an array of \a samples samples
representing one channel. The samples need not be block-aligned,
but each channel should have the same number of samples. Each sample
should be a signed integer, right-justified to the resolution set by
FLAC__stream_encoder_set_bits_per_sample(). For example, if the
resolution is 16 bits per sample, the samples should all be in the
range [-32768,32767].
Submit data for encoding.
This version allows you to supply the input data where the channels
are interleaved into a single array (i.e. channel0_sample0,
channel1_sample0, … , channelN_sample0, channel0_sample1, …).
The samples need not be block-aligned but they must be
sample-aligned, i.e. the first value should be channel0_sample0
and the last value channelN_sampleM. Each sample should be a signed
integer, right-justified to the resolution set by
FLAC__stream_encoder_set_bits_per_sample(). For example, if the
resolution is 16 bits per sample, the samples should all be in the
range [-32768,32767].
Set to \c false to let the encoder estimate the best model order
based on the residual signal energy, or \c true to force the
encoder to evaluate all order models and select the best.
Set to \c true to enable mid-side encoding on stereo input. The
number of channels must be 2 for this to have any effect. Set to
\c false to use only independent channel coding.
Set to \c false to use only the specified quantized linear predictor
coefficient precision, or \c true to search neighboring precision
values and use the best one.
Set to \c true to enable adaptive switching between mid-side and
left-right encoding on stereo input. Set to \c false to use
exhaustive searching. Setting this to \c true requires
FLAC__stream_encoder_set_do_mid_side_stereo() to also be set to
\c true in order to have any effect.
Set the maximum partition order to search when coding the residual.
This is used in tandem with
FLAC__stream_encoder_set_min_residual_partition_order().
Set the metadata blocks to be emitted to the stream before encoding.
A value of \c NULL, \c 0 implies no metadata; otherwise, supply an
array of pointers to metadata blocks. The array is non-const since
the encoder may need to change the \a is_last flag inside them, and
in some cases update seek point offsets. Otherwise, the encoder will
not modify or free the blocks. It is up to the caller to free the
metadata blocks after encoding finishes.
Set the minimum partition order to search when coding the residual.
This is used in tandem with
FLAC__stream_encoder_set_max_residual_partition_order().
Set the Subset flag. If \c true,
the encoder will comply with the Subset and will check the
settings during FLAC__stream_encoder_init_*() to see if all settings
comply. If \c false, the settings may take advantage of the full
range that the format allows.
Set an estimate of the total samples that will be encoded.
This is merely an estimate and may be set to \c 0 if unknown.
This value will be written to the STREAMINFO block before encoding,
and can remove the need for the caller to rewrite the value later
if the value is known before encoding.
Set the “verify” flag. If \c true, the encoder will verify it’s own
encoded output by feeding it through an internal decoder and comparing
the original signal against the decoded signal. If a mismatch occurs,
the process call will return \c false. Note that this will slow the
encoding process by the extra time required for decoding and comparison.
Signature for the EOF callback.
The signature and semantics mostly match POSIX feof() but WATCHOUT:
on many systems, feof() is a macro, so in this case a wrapper function
must be provided instead.
Signature for the seek callback.
The signature and semantics mostly match POSIX fseek() WITH ONE IMPORTANT
EXCEPTION: the offset is a 64-bit type whereas fseek() is generally ‘long’
and 32-bits wide.
Signature for the tell callback.
The signature and semantics mostly match POSIX ftell() WITH ONE IMPORTANT
EXCEPTION: the offset is a 64-bit type whereas ftell() is generally ‘long’
and 32-bits wide.
Possible values passed back to the FLAC__StreamDecoder error callback.
\c FLAC__STREAM_DECODER_ERROR_STATUS_LOST_SYNC is the generic catch-
all. The rest could be caused by bad sync (false synchronization on
data that is not the start of a frame) or corrupted data. The error
itself is the decoder’s best guess at what happened assuming a correct
sync. For example \c FLAC__STREAM_DECODER_ERROR_STATUS_BAD_HEADER
could be caused by a correct sync on the start of a frame, but some
data in the frame header was corrupted. Or it could be the result of
syncing on a point the stream that looked like the starting of a frame
but was not. \c FLAC__STREAM_DECODER_ERROR_STATUS_UNPARSEABLE_STREAM
could be because the decoder encountered a valid frame made by a future
version of the encoder which it cannot parse, or because of a false
sync making it appear as though an encountered frame was generated by
a future encoder.