Struct flac_bound::FlacEncoder

source · [−]
#[repr(transparent)]
pub struct FlacEncoder<'out>(_, _);
Expand description

The stream encoder can encode to native FLAC, and optionally Ogg FLAC (check FLAC_API_SUPPORTS_OGG_FLAC) streams and files.

The basic usage of this encoder is as follows:

In more detail, the stream encoder functions similarly to the stream decoder, but has fewer callbacks and more options. Typically the client will create a new instance by calling FlacEncoder::new(), then set the necessary parameters with functions on FlacEncoderConfig, and initialize it by calling one of the FlacEncoderConfig::init_*() functions.

Unlike the decoders, the stream encoder has many options that can affect the speed and compression ratio. When setting these parameters you should have some basic knowledge of the format (see the user-level documentation or the formal description). The functions on FlacEncoderConfig themselves do not validate the values as many are interdependent. The FlacEncoderConfig::init_*() functions will do this, so make sure to pay attention to the result returned by FlacEncoderConfig::init_*() to make sure that it is Ok(). Any parameters that are not set before FlacEncoderConfig::init_*() will take on the defaults from the constructor.

There are three initialization functions for native FLAC, one for setting up the encoder to encode FLAC data to the client via a Write stream, and two for encoding directly to a file.

For encoding via a Write stream, use FlacEncoderConfig::init_write(). You must also supply a std::io::Write stream which will be called anytime there is raw encoded data to write. The client cannot seek the output due to RFC 2035, so the encoder cannot go back after encoding is finished to write back information that was collected while encoding, like seek point offsets, frame sizes, etc.

For encoding directly to a file, use FlacEncoderConfig::init_file(). Then you must only supply a UTF-8 filename; the encoder will handle all the callbacks internally. You may also supply a progress callback for periodic notification of the encoding progress.

There are three similarly-named init functions for encoding to Ogg FLAC streams.

The call to FlacEncoderConfig::init_*() currently will also immediately call write to the sink several times, once with the fLaC signature, and once for each encoded metadata block. Note that for Ogg FLAC encoding you will usually get at least twice the number of callbacks than with native FLAC, one for the Ogg page header and one for the page body.

After initializing the instance, the client may feed audio data to the encoder in one of two ways:

  • Channel separate, through FlacEncoder::process() - The client will pass an slice of buffer slices, one for each channel, to the encoder, each of the same length. The samples need not be block-aligned, but each channel should have the same number of samples. This function will allocate if the user supplies more than 8 channels.
  • Channel interleaved, through FlacEncoder::process_interleaved() - The client will pass a single slice to data that is channel-interleaved (i.e. channel0_sample0, channel1_sample0, … , channelN_sample0, channel0_sample1, …). Again, 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.

Note that for either process call, each sample in the buffers should be a signed integer, right-justified to the resolution set by FlacEncoderConfig::bits_per_sample(). For example, if the resolution is 16 bits per sample, the samples should all be in the range [-32768,32767].

When the client is finished encoding data, it calls FlacEncoder::finish(), either explicitly or by dropping the encoder, which causes the encoder to encode any data still in its input pipe, and call the metadata callback with the final encoding statistics. Then the instance may be deleted with FlacEncoder::delete() by dropping the encoder, or initialized again to encode another stream.

For programs that write their own metadata, but that do not know the actual metadata until after encoding, it is advantageous to instruct the encoder to write a PADDING block of the correct size, so that instead of rewriting the whole stream after encoding, the program can just overwrite the PADDING block. If only the maximum size of the metadata is known, the program can write a slightly larger padding block, then split it after encoding.

Make sure you understand how lengths are calculated. All FLAC metadata blocks have a 4 byte header which contains the type and length. This length does not include the 4 bytes of the header. See the format page for the specification of metadata blocks and their lengths.

Note:
If you are writing the FLAC data to a file via callbacks, make sure it is open for update (e.g. mode “w+” for stdio streams). This is because after the first encoding pass, the encoder will try to seek back to the beginning of the stream, to the STREAMINFO block, to write some data there. (If using FlacEncoderConfig::init_file(), the file is managed internally.)

Note:
FlacEncoder::finish() resets all settings to the constructor defaults.

Implementations

Create a new stream encoder, in a configuration wrapper, or None if one couldn’t be allocated.

Get the current encoder state.

Get the state of the verify stream decoder.

Useful when the stream encoder state is VerifyDecoderError.

Submit data for encoding.

This version allows you to supply the input data via a slice of slices, each slice consisting of the same amount of samples as the first one, 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 FlacEncoderConfig::bits_per_sample(). For example, if the resolution is 16 bits per sample, the samples should all be in the range [-32768,32767].

For applications where channel order is important, channels must follow the order as described in the frame header.

Requires encoder instance to be in OK state.

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 FlacEncoderConfig::bits_per_sample(). For example, if the resolution is 16 bits per sample, the samples should all be in the range [-32768,32767].

For applications where channel order is important, channels must follow the order as described in the frame header.

Requires encoder instance to be in OK state.

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.

Note that in the course of processing the last frame, errors can occur, so the caller should be sure to check the return value to ensure the file was encoded properly.

In the event of a prematurely-terminated encode, it is not strictly necessary to call this immediately before FlacEncoder::delete() but it is good practice to match every FlacEncoderConfig::init_*() with a FlacEncoder::finish().

This is also called by drop().

Returns Err(self) if an error occurred processing the last frame, or, if verify mode is set (see FlacEncoderConfig::verify()), there was a verify mismatch; else the config wrapper.

If Err(), caller should check the state with state() for more information about the error.

Trait Implementations

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.